openapi.yaml

swagger: "2.0"
info:
  description: "Botfront API"
  title: "Botfront API"
consumes:
  - "application/json"
produces:
  - "application/json"
schemes:
  - "https"

paths:
  "/project/{project_id}/response/name/{name}/lang/{lang}":
    get:
      summary: Retrieve a bot response with its name
      description: >
        A bot response is a sequence of messages in the Botfront format. The JSON example below shows a simple text message but all the Botfront message types (Quick replies, images, Facebook templates, ...) can be returned in that array. 
        Use the Bot Responses section of the Botfront app for a complete refence ( in `yaml`).
      operationId: getBotResponse
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
        - name: name
          in: path
          description: Bot response name
          required: true
          type: string
        - name: lang
          in: path
          description: The bot response language
          required: true
          type: string
        - name: metadata
          in: query
          description: if metadata is set to 1, the metadata field will be included in the response sequence
          required: false
          type: integer
      responses:
        default:
          description: Unknown error
        400:
          description: Bad request
        404:
          description: Project not found
        403:
          description: Unauthorized
        200:
          description: Succesfull response
          schema:
            $ref: "#/definitions/sequence"

  "/project/{project_id}/responses":
    get:
      operationId: getAllResponses
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
        - name: timestamp
          in: query
          description: timestamp in ms of last update
          required: false
          type: number
        - name: metadata
          in: query
          description: if metadata is set to 1, the metadata field will be included in the response sequence
          required: false
          type: integer
      produces:
        - application/json
      summary: Retrieve all bot responses. If you pass the `timestamp` query param it will compare it with the last update time of the responses. If they have not been modified, a 304 response is returned. This allows to periodically check for updates
      responses:
        default:
          description: Unknown error
        403:
          description: Unauthorized
        200:
          description: OK
          schema:
            $ref: "#/definitions/bot_responses"
        304:
          description: Not modified

  "/project/{project_id}/response":
    post:
      operationId: getResponse
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
        - in: body
          name: body
          description: NLU information the response should match
          schema:
            $ref: "#/definitions/matching_criteria"
        - name: metadata
          in: query
          description: if metadata is set to 1, the metadata field will be included in the response sequence
          required: false
          type: integer
      produces:
        - application/json
      summary: Retrieve a bot response matching NLU criteria
      description: >
        A bot response is a sequence of messages in the Botfront format. The JSON example below shows a simple text message but all the Botfront message types (Quick replies, images, Facebook templates, ...) can be returned in that array. 
        Use the Bot Responses section of the Botfront app for a complete refence ( in `yaml`). 

        Note that if the `language` parameter is ommited, only the `key` will be returned, not the sequence
      responses:
        default:
          description: Unknown error
        400:
          description: Bad request
        404:
          description: Project not found
        403:
          description: Unauthorized
        200:
          description: OK
          schema:
            $ref: "#/definitions/bot_response"

  # "/project/{project_id}/tracker/{sender_id}/tag/{tag}":
  #   get:
  #     summary: Legacy tracker update endpoint.
  #     operationId: getTracker
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     - name: sender_id
  #       in: path
  #       description: Conversation senderId
  #       required: true
  #       type: string
  #     - name: tag
  #       in: path
  #       description: "`development` or `production`"
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/conversations/{sender_id}/{event_count}":
  #   get:
  #     summary: Gets a tracker with the `event_count` latest events.
  #     operationId: getConversation
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     - name: sender_id
  #       in: path
  #       description: Conversation senderId
  #       required: true
  #       type: string
  #     - name: event_count
  #       in: path
  #       description: The number of events to fetch with the tracker
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/conversations/{sender_id}/insert":
  #   post:
  #     summary: Creates a new tracker.
  #     # description: Parse an utterance and returns NLU structured output.
  #     operationId: insertUpdateTracker
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     - name: sender_id
  #       in: path
  #       description: Conversation senderId
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/conversations/{sender_id}/update":
  #   post:
  #     summary: Updates conversation tracker.
  #     # description: Parse an utterance and returns NLU structured output.
  #     operationId: postUpdateTracker
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     - name: sender_id
  #       in: path
  #       description: Conversation senderId
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/rules":
  #   get:
  #     summary: Returns CORE rules.
  #     # description: Parse an utterance and returns NLU structured output.
  #     operationId: getRules
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/credentials":
  #   get:
  #     summary: Returns CORE channels credentials.
  #     # description: Parse an utterance and returns NLU structured output.
  #     operationId: getCredentials
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  # "/project/{project_id}/endpoints":
  #   get:
  #     summary: Returns CORE endpoints.
  #     # description: Parse an utterance and returns NLU structured output.
  #     operationId: getEndpoints
  #     parameters:
  #     - name: project_id
  #       in: path
  #       description: Botfront project ID
  #       required: true
  #       type: string
  #     responses:
  #       default:
  #         description: Unknown error
  #       400:
  #         description: Bad request
  #       404:
  #         description: Project not found
  #       403:
  #         description: Unauthorized
  #       200:
  #         description: Ok

  "/project/{project_id}/models/published":
    get:
      summary: Returns the list of published NLU models.
      # description: Parse an utterance and returns NLU structured output.
      operationId: getModelsPublished
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
      responses:
        default:
          description: Unknown error
        400:
          description: Bad request
        404:
          description: Project not found
        403:
          description: Unauthorized
        200:
          description: Ok

  "/conversations/{projectId}/environment/{env}/latest-imported-event":
    get:
      operationId: getLastestImportedEvent,
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
        - name: env
          in: path
          description: environement to get latest imported event from, should be one of production, development
          required: true
          type: string
      produces:
        - application/json
      responses:
        default:
          description: Unknown error
        400:
          description: Bad request
          schema: { error: <errorMessage> }
        401:
          description: Unauthorized
        200:
          description: OK
          schema:
            $ref: "#/definitions/timestamp"
        500:
          description: Internal Server Error

  "/conversations/{projectId}/environment/{env}":
    post:
      operationId: importNewConversation,
      parameters:
        - name: project_id
          in: path
          description: Botfront project ID
          required: true
          type: string
        - name: env
          in: path
          description: environement to import to, should be one of production, development
          required: true
          type: string
        - name: conversations
          in: body
          description: conversations to import
          required: true
          type: array
          schema:
            $ref: "#/definitions/conversations"
        - name: processNlu
          in: body
          description: copy parse_data to activity if true
          required: true
          type: boolean
      produces:
        - application/json
      responses:
        default:
          description: Unknown error
        400:
          description: Bad request
          summary: the format of the parameters was not correct
        401:
          description: Unauthorized
        206:
          description: Partial Content
          summary: some parts of the data were not formated correctly and not added, they are returned in the response body
        200:
          description: OK
        500:
          description: Internal Server Error

  "/api-docs":
    get:
      summary: API documentation
      security: []
      # description: Parse an utterance and returns NLU structured output.
      operationId: apiDocs
      responses:
        default:
          description: Unknown error
        200:
          description: Ok

  "/api-docs/{file}":
    get:
      summary: API documentation
      parameters:
        - name: file
          in: path
          description: Botfront project ID
          required: true
          type: string
      security: []
      # description: Parse an utterance and returns NLU structured output.
      operationId: apiDocsDeps
      responses:
        default:
          description: Unknown error
        200:
          description: Ok

definitions:
  matching_criteria:
    type: object
    properties:
      nlu:
        type: object
        properties:
          intent:
            type: string
            example: greet
          entities:
            type: array
            items:
              type: object
              properties:
                entity:
                  type: string
                  example: city
                value:
                  type: string
                  example: Paris
  bot_response:
    type: object
    properties:
      key:
        type: string
        example: utter_something
      follow_up:
        type: string
        example: utter_something
      values:
        type: array
        items:
          $ref: "#/definitions/sequence"
  sequence:
    description: test
    type: array
    items:
      $ref: "#/definitions/quick_replies"

  timestamp:
    properties:
      timestamp:
        type: integer
        example: 1550677361363

  message:
    type: object
    properties:
      text:
        type: string
        example: Something

  conversations:
    definition: array of conversation element from the db
    type: array
    items:
      type: object

  bot_responses:
    type: object
    properties:
      timestamp:
        type: integer
        example: 1550677361363
      responses:
        type: array
        items:
          type: object
          properties:
            key:
              type: string
              example: utter_something
            value:
              type: array
              items:
                type: object
                properties:
                  sequence:
                    $ref: "#/definitions/sequence"
                  lang:
                    type: string
                    example: "fr"
            match:
              type: object
              $ref: "#/definitions/matching_criteria"

  quick_replies:
    type: object
    properties:
      text:
        type: string
        example: Something
      buttons:
        type: array
        items:
          type: object
          properties:
            title:
              type: string
              example: "Yes"
            payload:
              type: string
              example: "/basics.yes"

security:
  - api_key: []

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"