openapi: "3.0.1"
info:
  title: "Rasa Platform - Data"
  version: "1.0.0"
  description: >-
    Rasa Platform data endpoints
servers:
- url: http://demo-bot.rasa.com/api
  description: Demo
paths:
  /projects/{project_id}/data:
    get:
      tags:
      - Data
      summary: Get training examples
      operationId: getData
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - in: query
        name: q
        description: Search string
        schema:
          type: string
      - in: query
        name: intent
        description: Intents to filter on
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: integer
          default: null
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
      - in: query
        name: sorted
        schema:
          type: boolean
      responses:
        200:
          description: Training examples for project
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total responses ignoring limit and offset
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrainingExample'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
      - Data
      summary: Add new training example
      operationId: addData
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainingExample'
      responses:
        200:
          description: New training example
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingExample'
        400:
          description: wrong schema
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: example could not be saved
    put:
      tags:
      - Data
      summary: Replace training data in bulk
      operationId: replaceBulkData
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rasa_nlu_data:
                  type: object
                  properties:
                    common_examples:
                      type: array
                      items:
                        $ref: '#/components/schemas/TrainingExample'
          text/markdown:
            schema:
              type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: string
                    enum:
                    - data uploaded
        400:
          description: wrong schema, training data could not be uploaded
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /projects/{project_id}/data.json:
    get:
      tags:
      - Data
      summary: Download traning examples in JSON format
      operationId: getDataJson
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      responses:
        200:
          description: Attachment of traning examples in JSON
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /projects/{project_id}/data/{example_id}:
    put:
      tags:
      - Data
      summary: Update a training example by id
      operationId: updateExample
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/exampleId'
      requestBody:
        required: True
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainingExample'
      responses:
        200:
          description: Updated training example
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingExample'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: training example could not be updated
    delete:
      tags:
      - Data
      summary: Delete a training example by id
      operationId: deleteData
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/exampleId'
      responses:
        200:
          description: Confirmation of example being deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: string
                    description: example {example_id} deleted
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: training data could not be deleted

  /projects/{project_id}/data/{hash}:
    put:
      tags:
      - Data
      summary: Update a training example by id
      operationId: updateExample
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/hash'
      responses:
        200:
          description: Training example
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingExample'
        400:
          description: training example could not be found
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /projects/{project_id}/dataWarnings:
    get:
      tags:
      - Data
      summary: Get warnings about training data.
      operationId: getDataWarnings
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      responses:
        200:
          description: Warnings about training data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataWarning'
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /projects/{project_id}/entities:
    get:
      tags:
      - Data
      summary: Available entities
      description: Unique entity types present in the training data.
      operationId: getEntities
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      responses:
        200:
          description: Unique entities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /projects/{project_id}/logs:
    get:
      tags:
      - Suggestions
      summary: Get suggestions
      operationId: getLogs
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/q'
      - in: query
        name: intent
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: integer
          default: null
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
      responses:
        200:
          description: Suggestions for project
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total responses ignoring limit and offset
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suggestion'
    post:
      tags:
      - Parsing
      summary: Parse text and create a new log entry
      operationId: parseText
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/q'
      responses:
        200:
          description: Created log entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'

  /projects/{project_id}/logs/{log_id}:
    delete:
      tags:
      - Logs
      summary: Archive log
      operationId: archiveLog
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - in: path
        name: log_id
        schema:
          type: string
        required: true
      responses:
        200:
          description: Successfully archived log
          content:
            text/plain:
              schema:
                type: string
                description: log {log_id} archived
        400:
          description: archiving of logs unsuccessful

  /projects/{project_id}/logs/{hash}:
    get:
      tags:
      - Logs
      summary: Fetch log by its hash
      operationId: getLogByHash
      parameters:
      - $ref: './common.yml#/components/parameters/projectId'
      - $ref: '#/components/parameters/hash'
      responses:
        200:
          description: Successfully fetched log log
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        400:
          description: Fetching of log unsuccessful

  /nlg:
    post:
      tags:
      - NLG
      summary: Get NLG response
      operationId: postNLGRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NlgRequest'
      responses:
        200:
          description: Generated NLG response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NlgResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /responses:
    get:
      tags:
      - NLG
      summary: Get bot responses
      operationId: getResponses
      parameters:
      - in: query
        name: q
        schema:
          type: string
        description: Template text search string
      - in: query
        name: template
        schema:
          type: string
        description: Templates to filter on (comma-separated)
      - in: query
        name: limit
        schema:
          type: number
          default: null
        description: Limit number of responses to return
      - in: query
        name: offset
        schema:
          type: number
          default: 0
        description: Offset to consider in window of responses returned
      responses:
        200:
          description: Bot responses
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: Total responses ignoring limit and offset
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NlgResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
      - NLG
      summary: Add to responses collection
      operationId: postResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NlgResponse'
      responses:
        200:
          description: Response ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NlgResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    put:
      tags:
      - NLG
      summary: Replace bot responses in bulk
      operationId: replaceResponses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/NlgResponse'
      responses:
        200:
          description: Upload successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: string
                    example:
                    - Successfully uploaded 35 responses.
        400:
          description: wrong schema, responses could not be uploaded
        401:
          $ref: '#/components/responses/UnauthorizedError'

  /responses/{response_id}:
    put:
      tags:
      - NLG
      summary: Modify NLG response
      operationId: modifyResponse
      parameters:
      - $ref: '#/components/parameters/responseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NlgResponse'
      responses:
        200:
          description: Modified NLG response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NlgRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    delete:
      tags:
      - NLG
      summary: Delete an NLG response
      operationId: deleteResponse
      parameters:
      - $ref: '#/components/parameters/responseId'
      responses:
        204:
          description: Delete OK
          content:
            text/plain:
              schema:
                type: string
  /stories:
    get:
      tags:
      - Stories
      summary: Get saved stories
      operationId: getStories
      parameters:
      - in: query
        name: q
        description: Search string
        schema:
          type: string
      responses:
        200:
          description: Rasa Core stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RasaCoreStoryObject'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
      - Stories
      summary: Upload stories
      operationId: uploadStories
      requestBody:
        required: true
        content:
          text/markdown:
            schema:
              type: string
      responses:
        200:
          description: Uploaded stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RasaCoreStoryObject'
        400:
          description: Stories could not be uploaded
        401:
          $ref: '#/components/responses/UnauthorizedError'
    put:
      tags:
      - Stories
      summary: Replace stories
      operationId: replaceStories
      requestBody:
        required: true
        content:
          text/markdown:
            schema:
              type: string
      responses:
        200:
          description: Uploaded stories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RasaCoreStoryObject'
        400:
          description: Stories could not be uploaded
        401:
          $ref: '#/components/responses/UnauthorizedError'
  /stories.md:
    get:
      tags:
      - Stories
      summary: Get stories as markdown file
      operationId: getStories
      parameters:
      - in: query
        name: q
        description: Search string
        schema:
          type: string
      responses:
        200:
          description: Rasa Core stories as markdown file
          content:
            text/markdown:
              schema:
                type: string
        401:
          $ref: '#/components/responses/UnauthorizedError'
  /stories/{story_id}:
    put:
      tags:
      - Stories
      summary: Modify Rasa Core story
      operationId: modifyStory
      parameters:
      - $ref: '#/components/parameters/storyId'
      requestBody:
        required: true
        content:
          text/markdown:
            schema:
              type: string
      responses:
        200:
          description: Modified Rasa Core story
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RasaCoreStoryObject'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    delete:
      tags:
      - Stories
      summary: Delete a Rasa Core Story
      operationId: deleteStory
      parameters:
      - $ref: '#/components/parameters/storyId'
      responses:
        204:
          description: Delete OK
          content:
            text/plain:
              schema:
                type: string
        401:
          $ref: '#/components/responses/UnauthorizedError'
security:
- bearerAuth: []
components:
  parameters:
    responseId:
      in: path
      name: response_id
      example: 5bb89a7e3b18fb3d95495f2e
      description: response ID
      schema:
        type: string
      required: true
    exampleId:
      in: path
      name: example_id
      example: 5bb89a7f3b18fb3d95495f30
      description: example ID
      schema:
        type: string
      required: true
    storyId:
      in: path
      name: story_id
      example: 5bb89a7f3b18fb3d95495f31
      description: story ID
      schema:
        type: string
      required: true
    hash:
      in: path
      name: hash
      example: b10a8db164e0754105b7a99be72e3fe5
      description: MD5 hash of an NLU example's text field
      schema:
        type: string
      required: true
    q:
      in: query
      name: q
      description: query string
      schema:
        type: string
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              exception:
                type: string
              reasons:
                oneOf:
                - type: string
                - type: array
                  items:
                    type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    NlgResponse:
      type: object
      description: Generated bot response
      required:
      - text
      - template
      properties:
        text:
          type: string
        buttons:
          type: array
          items:
            type: string
        image:
          type: string
          nullable: true
        elements:
          type: array
          items:
            type: string
        attachment:
          type: string
        template:
          type: string
        id:
          type: string
    NlgRequest:
      type: object
      description: Request object for NLG
      properties:
        tracker:
          type: object
        arguments:
          type: object
        template:
          type: string
        channel:
          type: object
    RasaCoreStory:
      type: string
      description: Rasa Core story in Markdown format
    RasaCoreStoryObject:
      type: object
      properties:
        story:
          $ref: '#/components/schemas/RasaCoreStory'
        id:
          type: string
        annotation:
          type: object
          properties:
            user:
              type: string
            time:
              type: number
            name:
              type: string
    TrainingExample:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        intent:
          type: string
        entities:
          type: array
          items:
            type: object
            required:
            - start
            - end
            - value
            - entity
            properties:
              start:
                oneOf:
                - type: string
                - type: integer
              end:
                oneOf:
                - type: string
                - type: integer
              entity:
                oneOf:
                - type: string
                - type: integer
              value:
                oneOf:
                - type: string
                - type: integer
        hash:
          type: string
        intent_mapped_to:
          type: string
          description: >-
            Name of the intent which the intent is mapped to.
            If the intent is a temporary one, it has to be mapped to an existing
            one to be part of the training. If its value is `null` it deletes
            existing mappings.
    DataWarning:
      type: object
      description: A warning tells you there are too few or too many of something. The warning will also return the `min` or `max` number that is acceptable, and the current count. For example, if you have <2 examples for one of your intents, you will receive a warning about the `dataPerIntent` with a `min` of 2 and a `count` of 1.
      properties:
        type:
          type: string
          enum: [data, blankIntent, intent, dataPerIntent]
          description: >
            Entity being warned about
            * `data` - Training data.
            * `blankIntent` - Training data with blank intent values.
            * `intent` - Intents to which your training data are classified.
            * `dataPerIntent` - Training data classified to the intent specified in `meta`.
        min:
          type: integer
          nullable: true
          description: Either `min` or `max` will always be present
        max:
          type: integer
          nullable: true
          description: Either `min` or `max` will always be present
        count:
          type: integer
        meta:
          nullable: true
          oneOf:
          - type: string
          - type: object
    Entity:
      type: object
      description: Rasa NLU entity object
      properties:
        entity:
          type: string
          description: entity type
          example: cuisine
    Suggestion:
      type: object
      description: Rasa NLU training example suggestion
      properties:
        user_input:
          type: object
          properties:
            text:
              type: string
            intent:
              type: object
              properties:
                name:
                  type: string
                confidence:
                  type: number
            entities:
              type: array
              items:
                type: object
        project_id:
          type: string
        hash:
          type: string
        model:
          type: string
        time:
          type: number
        team:
          type: string
