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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
        - 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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
        - in: path
          name: example_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
        - in: path
          name: example_id
          schema:
            type: string
          required: true
      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}/dataWarnings:
    get:
      tags:
        - Data
      summary: Get warnings about training data.
      operationId: getDataWarnings
      parameters:
        - in: path
          name: project_id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Warnings about training data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataWarning'
        401:
          $ref: '#/components/responses/UnauthorizedError'
  /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: object
                properties:
                  responses:
                    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'
  /responses/{response_id}:
    put:
      tags:
        - NLG
      summary: Modify NLG response
      operationId: modifyResponse
      parameters:
        - in: path
          name: response_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: response_id
          schema:
            type: string
          required: true
      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'
  /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:
        - in: path
          name: story_id
          schema:
            type: string
          required: true
      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:
        - in: path
          name: story_id
          schema:
            type: string
          required: true
      responses:
        204:
          description: Delete OK
          content:
            text/plain:
              schema:
                type: string
        401:
          $ref: '#/components/responses/UnauthorizedError'
security:
  - bearerAuth: []
components:
  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
      properties:
        text:
          type: string
        buttons:
          type: array
          items:
            type: string
        image:
          type: string
          nullable: true
        elements:
          type: array
          items:
            type: string
        attachment:
          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
    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
