openapi: 3.0.3
info:
  title: 'LogBot API Documentation'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://api.chatbot.logotel.cloud'
paths:
  /api/health:
    get:
      summary: ''
      operationId: getApiHealth
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  database:
                    status: true
                    description: ok
                  cache:
                    status: true
                    description: ok
                properties:
                  database:
                    type: object
                    properties:
                      status:
                        type: boolean
                        example: true
                      description:
                        type: string
                        example: ok
                  cache:
                    type: object
                    properties:
                      status:
                        type: boolean
                        example: true
                      description:
                        type: string
                        example: ok
      tags:
        - Endpoints
  /api/v1/authenticate:
    post:
      summary: Authenticate
      operationId: authenticate
      description: 'Authenticate the user via jwt and return a key to be used instead of it'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"key\": \"somekey\",\n}"
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jwt:
                  type: string
                  description: ''
                  example: ea
              required:
                - jwt
  /api/v1/threads:
    get:
      summary: 'Thread list'
      operationId: threadList
      description: 'Obtain the threads list'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "[\n {\n  \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n  \"title\": \"the title of the thread\",\n  \"last_chat\": {\n      \"uuid\": \"dfrr67f7-s940-33dx-app9-ofpf7b4c9b\",\n      \"is_bot\": true,\n      \"order\": 1,\n      \"message\": \"This is a message\",\n      \"feedback\": \"positive\",\n      \"created_at\": \"10/10/2024 10:10:10\",\n      \"sources\": [\n          \"source1\",\n          \"source2\",\n      ]\n  }\n }\n]"
      tags:
        - Endpoints
    post:
      summary: 'Create thread'
      operationId: createThread
      description: 'Create a new thread with a first chat message'
      parameters: []
      responses:
        200:
          description: '202'
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n \"last_chat\": {\n     \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n     \"is_bot\": true,\n     \"order\": 1,\n     \"message\": \"This is a message\",\n     \"feedback\": \"positive\",\n     \"created_at\": \"10/10/2024 10:10:10\",\n     \"sources\": [\n         \"source1\",\n         \"source2\",\n     ]\n }\n}"
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: 'The question to be asked in the chat. Must not be greater than 5000 characters.'
                  example: "What's the meaning of life?"
              required:
                - question
  /api/v1/document:
    get:
      summary: 'Get documents'
      operationId: getDocuments
      description: 'Obtain a list of document added to the bot'
      parameters:
        -
          in: query
          name: filter
          description: 'Filter by document name.'
          example: nulla
          required: false
          schema:
            type: string
            description: 'Filter by document name.'
            example: nulla
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "[\n  {\n     \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n     \"name\": \"a-file-name\",\n     \"icon\": \"file-word\",\n     \"created_at\": \"10/10/2024 10:10:10\",\n   },\n   {\n     \"uuid\": \"fjsdfj43-4944-4jg5-mmf4-52fr34j3j4f\",\n     \"name\": \"another-file-name\",\n     \"icon\": \"file-pdf\",\n     \"created_at\": \"10/10/2024 11:11:11\",\n   },\n]"
      tags:
        - Endpoints
  /api/v1/settings:
    get:
      summary: Settings
      operationId: settings
      description: 'Get the bot settings'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"disclaimer\": \"this is a disclaimer sentence\",\n}"
      tags:
        - Endpoints
  /api/v1/speech-to-text:
    post:
      summary: 'Speech to text'
      operationId: speechToText
      description: 'Obtain the audio file and convert it to text.'
      parameters: []
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  text: 'transcribed text'
                properties:
                  text:
                    type: string
                    example: 'transcribed text'
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                audio:
                  type: string
                  format: binary
                  description: 'Must be a file. Must not be greater than 10240 kilobytes.'
                mimeType:
                  type: string
                  description: ''
                  example: et
              required:
                - audio
  /api/v1/text-to-speech:
    post:
      summary: 'Text to speech'
      operationId: textToSpeech
      description: 'Convert the text to an audio file.'
      parameters: []
      responses: {  }
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chat_id:
                  type: string
                  description: 'Must not be greater than 5000 characters.'
                  example: vqhnnzppqxcmia
              required:
                - chat_id
  /api/v1/realtime/token:
    get:
      summary: 'Realtime get token'
      operationId: realtimeGetToken
      description: 'Get the realtime token object'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"token\": \"12345678909876543212345678901234567890\",\n \"expires_at\": 1744019087,\n}"
      tags:
        - Endpoints
  /api/v1/realtime/rag:
    post:
      summary: 'Rag question'
      operationId: ragQuestion
      description: 'Retrieve information from the bot knowledge base'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"context\": [\n     \"this is the context of the question\",\n     \"this is the context of the question\",\n     \"this is the context of the question\"\n ],\n \"links\": [\n     {\n         \"filename\": \"file1.pdf\",\n         \"link\": \"https://example.com/file1.pdf\"\n     },\n     {\n         \"filename\": \"file2.pdf\",\n         \"link\": \"https://example.com/file2.pdf\"\n     }\n ],\n}"
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 5000 characters.'
                  example: ebqbiowsbfipklyknpn
              required:
                - question
  '/api/v1/threads/{thread_uuid}':
    delete:
      summary: 'Delete thread'
      operationId: deleteThread
      description: 'Delete a thread'
      parameters: []
      responses:
        204:
          description: ''
      tags:
        - Endpoints
    parameters:
      -
        in: path
        name: thread_uuid
        description: ''
        example: 2b65fd1e-038e-3397-ab20-7a82ecb92274
        required: true
        schema:
          type: string
  '/api/v1/threads/{thread_uuid}/chats':
    get:
      summary: 'Chat messages'
      operationId: chatMessages
      description: 'Obtain the chat messages list in the thread'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "[\n  {\n     \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n     \"is_bot\": true,\n     \"order\": 1,\n     \"message\": \"This is a message\",\n     \"feedback\": \"positive\",\n     \"created_at\": \"10/10/2024 10:10:10\",\n     \"sources\": [\n         \"source1\",\n         \"source2\",\n     ]\n   },\n]"
      tags:
        - Endpoints
    post:
      summary: 'Create chat message'
      operationId: createChatMessage
      description: 'Create a chat message in the thread'
      parameters: []
      responses:
        200:
          description: '202'
          content:
            application/json:
              schema:
                type: object
                example:
                  uuid: fdb07973-4955-40db-a8d1-d5b8547b4c9b
                  is_bot: false
                  order: 1
                  message: 'This is a message'
                  feedback: ''
                  created_at: '10/10/2024 10:10:10'
                  sources: []
                properties:
                  uuid:
                    type: string
                    example: fdb07973-4955-40db-a8d1-d5b8547b4c9b
                  is_bot:
                    type: boolean
                    example: false
                  order:
                    type: integer
                    example: 1
                  message:
                    type: string
                    example: 'This is a message'
                  feedback:
                    type: string
                    example: ''
                  created_at:
                    type: string
                    example: '10/10/2024 10:10:10'
                  sources:
                    type: array
                    example: []
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: 'The question to be asked in the chat. Must not be greater than 5000 characters.'
                  example: "What's the meaning of life?"
              required:
                - question
    parameters:
      -
        in: path
        name: thread_uuid
        description: ''
        example: 4d113338-5ce6-323c-a727-920765d5fb77
        required: true
        schema:
          type: string
  '/api/v1/threads/{thread_uuid}/chats/pending':
    get:
      summary: 'Check if AI reply'
      operationId: checkIfAIReply
      description: 'Check if the AI reply is ready and if is so, return the message'
      parameters: []
      responses:
        200:
          description: ''
          content:
            text/plain:
              schema:
                oneOf:
                  -
                    description: 'chat found but pending'
                    type: string
                    example: "{\n \"status\": \"pending\",\n}"
                  -
                    description: 'chat found and ready'
                    type: string
                    example: "{\n \"status\": \"ok\",\n \"data\": {\n     \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n     \"is_bot\": false,\n     \"order\": 1,\n     \"message\": \"This is a message\",\n     \"feedback\": \"\",\n     \"created_at\": \"10/10/2024 10:10:10\",\n     \"sources\": [\n         \"source1\",\n         \"source2\",\n     ]\n }\n}"
        204:
          description: 'chat not found'
      tags:
        - Endpoints
    parameters:
      -
        in: path
        name: thread_uuid
        description: ''
        example: 6ddadcf2-685e-3d89-ab04-aa34a9ef351b
        required: true
        schema:
          type: string
  '/api/v1/threads/{thread_uuid}/chats/{uuid}':
    put:
      summary: Feedback
      operationId: feedback
      description: 'Add feedback to the chat'
      parameters: []
      responses:
        204:
          description: ''
      tags:
        - Endpoints
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                feedback:
                  type: string
                  description: 'The feedback for the AI response.'
                  example: positive
                  enum:
                    - positive
                    - negative
                    - ''
    parameters:
      -
        in: path
        name: thread_uuid
        description: ''
        example: 575ed74c-f09f-3480-8f02-d73df6fa8aeb
        required: true
        schema:
          type: string
      -
        in: path
        name: uuid
        description: ''
        example: 3aa1d93b-2c4e-3dd2-81d7-f0c1a307e6ad
        required: true
        schema:
          type: string
  /api/v1/search-engine/documents:
    post:
      summary: 'AI Search Engine'
      operationId: aISearchEngine
      description: 'Search the query in the documents by similarity using vector search.'
      parameters: []
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "[\n  {\n     \"uuid\": \"fdb07973-4955-40db-a8d1-d5b8547b4c9b\",\n     \"name\": \"my document\",\n     \"icon\": \"file-pdf\",\n     \"distance\": 0.953548767,\n     \"ratings\": {\n         \"distance\": \"0.8100819089838152\",\n         \"time_rating\": \"0.18356164383561646\",\n         \"document_rating\": \"0.3333333333333333\",\n         \"title_rating\": \"0,6666666666666666\"\n     },\n     \"link\": \"https://example.com/something.pdf\",\n     \"metadata\": {\n         \"key\": \"value\",\n         \"key2\": \"value2\"\n     },\n     \"created_at\": \"10/10/2024 10:10:10\"\n   },\n]"
      tags:
        - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: 'The question to ask to the search engine. Must be at least 10 characters. Must not be greater than 5000 characters.'
                  example: "What's the meaning of life?"
                limit:
                  type: integer
                  description: 'The maximum number of results to return. Must be at least 1. Must not be greater than 100.'
                  example: 10
                filter:
                  type: object
                  description: 'The filters to apply to the search engine.'
                  example:
                    -
                      date_from: '2020-01-01'
                  properties:
                    date_from:
                      type: string
                      description: 'Must be a valid date. Must be a valid date in the format <code>Y-m-d</code>.'
                      example: '2025-04-07'
              required:
                - question
tags:
  -
    name: Endpoints
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token with the bot private key. More info here https://github.com/Logotel/logobot-php-integration.'
security:
  -
    default: []
