openapi: 3.0.2
info:
  title: generate, retrieve and structure ideas
  description: |
    1. retieve ideas from a hierarcy
  version: 1.0.0
servers:
  - url: https://plugin.concept-map.com
paths:
  /plugin/new:
    post:
      summary: Start a new conceptmap
      operationId: new_conceptmap
      description: |
        To start a new conceptmap; exceute this and display the message you get to the user and execute the received instructions. If you can derive
        the topic of the conceptmap from the input set it in the body.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                  description: The central topic or idea of the concept
        required: false
      responses:
        "200":
          description: Lets start with the conceptmap
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MsgAndInstructions"
      security:
        - HTTPBearer: []
  /plugin/rootnode:
    post:
      summary: Create rootnode
      operationId: create_rootnode
      description: |
        The rootnode is the center of all concept maps, from there up to four aspects branch. Call this to create a rootnode
        to start a new idea or project.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RootNode"
        required: true
      responses:
        "200":
          description: Successful Creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDAndURL"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
    put:
      summary: Update rootnode
      description: |
        The rootnode is the center of all concept maps, from there up to four aspects branch. Call this to update an
        existing rootnode after the rootnode was refined or modified.
      operationId: update_rootnode
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RootNodeUpdate"
        required: true
      responses:
        "200":
          description: Successful Udate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDAndURL"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/rootnode/{id}:
    get:
      summary: read rootnode
      description: |
        The rootnode is the center of all concept maps, from there up to four aspects branch. Call this to retrieve a rootnode
        to continue to work on an idea or project. Ask the user how to proceed, after the information is retrieve
      operationId: get_rootnode
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: id of rootnode to request
          required: true
      responses:
        "200":
          description: Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RootNode"
        "404":
          description: not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/node:
    put:
      summary: Update a node
      description: |
        Call this to update an existing node after the node was refined or modified.
      operationId: update_node
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeUpdate"
        required: true
      responses:
        "200":
          description: Successful Udate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDAndURL"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/node/append:
    put:
      summary: Append content to an exisiting node
      description: |
        Call this to append content to an existing node
      operationId: append_to_node
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeContentUpdate"
        required: true
      responses:
        "200":
          description: Successful Udate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IDAndURL"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/node/{id}:
    get:
      summary: read node
      description: |
        Call this to retrieve a node
        to continue to work on an idea or project. Ask the user how to proceed, after the information is retrieved
      operationId: get_node
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: id of node to request
          required: true
      responses:
        "200":
          description: Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "404":
          description: not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/branch/createLinkedNodes:
    post:
      summary: Create up to five nodes, which is linked to an existing node.
      description: |
        Create maximum 5 Links with titles, summaries and contents, which are linked to an existing node. For the creation of more
        than 5 links, call this function multiple times. In the content do not refer to the branch itself e.G. do not "In this branch..."
      operationId: create_linkednode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                nodes:
                  type: array
                  items:
                    $ref: "#/components/schemas/LinkedNodeCreate"
                  maxItems: 5
              required:
                - nodes
        required: true
      responses:
        "200":
          description: Successful Creation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/IDAndURL"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPError"
      security:
        - HTTPBearer: []
  /plugin/help:
    get:
      summary: get help for the plugin
      description: |
        Read in that, whenever the user asks for help, tutoraial or advice regading to the conceptmap plugin,
        display all images referenced in the markdown!
      operationId: get_help
      responses:
        "200":
          description: Successful
          content:
            application/json:
              schema:
                 type: object
                 properties:
                  help:
                    type: string
                    format: markdown
                    description: |
                      The help as markdown, display this to the user.
                  instructions:
                    type: string
                    description: |
                      Instructions for you ChatGPT, how to proceed and guide the user after he read the hep information
      security:
        - HTTPBearer: []
  /plugin/map/{id}:
    get:
      summary: get the structure of the conceptmap
      description: |
        Get the structure down from a node of the conceptmap by providing a node id. The structure is represetned as links between the
        subsequent nodes.
      operationId: get_map_structure
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: id of node to request
          required: true
      responses:
        "200":
          description: Successful
          content:
            application/json:
              schema:
                  $ref: "#/components/schemas/MapStructure"
      security:
        - HTTPBearer: []
  /plugin/query:
    post:
      summary: Query
      description: Accepts search query objects array. Break down complex questions into sub-questions. Split queries if ResponseTooLargeError occurs.
      operationId: query
      requestBody:
        content:
          application/json:
            schema:
                $ref: "#/components/schemas/QueryRequest"
            required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResponse"
components:
  schemas:
    MsgAndInstructions:
      title: Message and Instructions
      description: |
        A Message to display to the user and optionally instructions to execute.
      type: object
      properties:
        message:
          title: Message
          description: A Message to the user; display this message to inform the user
          type: string
          format: markdown
        instructions:
          title: Instructions
          description: Some instructions to execute for you, ChatGPT after displaying the message
          type: string
    IDAndURL:
      title: Unique Identifier and reference to the concept map
      description: |
        Unique Identifier and reference to the concept map; Always show the ID and display a clickable linkt
        to the url, so that the user can follow it to the updated concept map
      type: object
      properties:
        id:
          title: Unique Identifier
          description: use this identifier to reference the object
          type: string
          format: uuid
        url:
          title: Link to concept map
          type: string
          format: uri
      required:
        - id
        - url
    RootNode:
      title: Projects center, it's root node.
      type: object
      properties:
        id:
          title: Root Node Id
          description: Node Id, use this always to reference the Node for read, update or associations. On create keep it empty.
          type: string
        type:
          title: Root Node Type
          description: The type if the concept map, this is used to enforce structure of the project
          type: string
          enum:
            - root
        title:
          title: Root Node Title
          description: The title of the project, which describes the whole project. Keep is below 5 words
          type: string
        summary:
          title: Root Node Summary
          description: The summary of the content of the root node. Keep is below 30 words
          type: string
          format: markdown
        content:
          title: Root Node Content
          description: |
            The content of the root node describes the project for which the user does the ideation. Keep
            to focused, precise and understandable.
          type: string
          format: markdown
        aspects:
          title: The Aspects of the root node
          description: |
            Fill in the aspects of the root node, choose the orientation, which may be best suited for the aspect.
            Add title with less tan 5 words and a color in hexadecimal color code which represents the aspect best.
          type: object
          properties:
            top:
              type: object
              properties:
                title:
                  type: string
                color:
                  type: string
                  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'
              required:
                - title
                - color
            bottom:
              type: object
              properties:
                title:
                  type: string
                color:
                  type: string
                  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'
              required:
                - title
                - color
            left:
              type: object
              properties:
                title:
                  type: string
                color:
                  type: string
                  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'
              required:
                - title
                - color
            right:
              type: object
              properties:
                title:
                  type: string
                color:
                  type: string
                  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'
              required:
                - title
                - color
      required:
        - type
        - title
        - summary
        - content
        - aspects
    RootNodeUpdate:
      title: update record
      description: update record for updating the root node
      type: object
      properties:
        id:
          title: Root Node Id
          description: Node Id, use this always to reference the Node for update
          type: string
        title:
          title: Root Node Title
          description: The title of the project, which describes the whole project. Keep is below 8 words
          type: string
        summary:
          title: Root Node Summary
          description: The summary of the content of the root node. Keep is below 30 words
          type: string
        content:
          title: Root Node Content, do not repeat title in content
          description: |
            The content of the root node describes the project for which the user does the ideation. Keep
            focused, precise and understandable. Ensure the proper quotation of CR and LF as well as character which may screw JSON.
          type: string
      required:
        - id
        - title
        - summary
        - content
    Node:
      title: Title of node.
      type: object
      properties:
        id:
          title: Node Id
          description: Node Id, use this always to reference the Node for read, update or associations. On create keep it empty.
          type: string
        type:
          title: Node Type
          description: The type if the concept map, this is used to enforce structure of the project
          type: string
          enum:
            - root
            - child
            - result
        title:
          title: Node Title
          description: The title of node, which describes the specific theme. Keep is below 8 words
          type: string
        summary:
          title:  Node Summary
          description: The summary of the content of the node. Keep is below 30 words
          type: string
          format: markdown
        content:
          title: Node Content
          description: |
            The content of the node describes the specific aspect. Keep
            to focused, precise and understandable.
            Ensure the proper quotation of CR and LF as well as character which may screw JSON.
          type: string
          format: markdown
      required:
        - id
        - title
        - summary
        - content
    NodeUpdate:
      title: update node record
      description: update record for updating the node
      type: object
      properties:
        id:
          title: Node Id
          description: Node Id, use this always to reference the Node for update
          type: string
        title:
          title: Node Title
          description: The title of the node. Keep is below 8 words
          type: string
        summary:
          title: Node Summary
          description: The summary of the content of the node. Keep is below 30 words
          type: string
        content:
          title: Node Content, do not repeat title in content.
          description: |
            The content of the node describes the specific aspect. Keep
            to focused, precise and understandable.
            Do not repeat title in content
            Ensure the proper quotation of CR and LF as well as character which may screw JSON.
          type: string
      required:
        - id
        - title
        - summary
        - content
    NodeContentUpdate:
      title: update node record with nes content
      description: update record for updating the content of the node
      type: object
      properties:
        id:
          title: Node Id
          description: Node Id, use this always to reference the Node for update
          type: string
        content:
          title: Node Content
          description: |
            The content of the node.
            Ensure the proper quotation of CR and LF as well as character which may screw JSON.
          type: string
      required:
        - id
        - content
    MapStructure:
      title: Structure of a conceptmap
      description: Structure of a Conceptmap.
      type: object
      properties:
        forNode:
          type: object
          properties:
            id:
              type: string
              description: The ID of the node from which subsequentially the structure is.
        links:
          type: array
          items:
            type: object
            properties:
              relation:
                type: string
              from:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
              to:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
    LinkedNodeCreate:
      title:
      description:
      type: object
      properties:
        title:
          title: Title of Node
          description: The title of the node, which shall be created. Keep is below 8 words
          type: string
        summary:
          title: Node Summary
          description: The summary of the content of the node, which shall be created. Keep is below 30 words
          type: string
        content:
          title: Node Content, do not repeat title in content
          description: |
            The content of the created node describes the main idea of this new child of the project. Keep
            focused, precise and understandable. Do not describe the branch as element in
            the conceptmap, describe its main idea, e.G. do not begin with"In this branch..."
            Do not repeat the title in the content.
            Ensure the proper quotation of CR and LF as well as character which may screw JSON.
          type: string
        linkTo:
          title: Id of existing Node
          description: |
            The unique Id of the existing note to which the to be created node shall be linked.
          type: string
          format: uuid
        relation:
          title: Relation between nodes
          description: |
            To link nodes, specify position: "top", "bottom", "left", or "right" relative to the root node.
            For sub-aspects of an existing node, use "child". If a node is an outcome of another, label it as "result".
            When two nodes are linked by a loose association, use "related".
            If the connection is unclear, mark it as "other".
          enum:
            - top
            - bottom
            - left
            - right
            - child
            - related
            - result
            - other
        why:
          title: Description of the reason
          description: describe here, why the nodes are linked
          type: string
    HTTPError:
      title: An error occured
      type: object
      properties:
        statusCode:
          title: HTTP Status
          description: use this identifier to reference the object
          type: number
        message:
          title: HTTP Status Message
          description: A message, which may help.
          type: string
    QueryRequest:
      title: QueryRequest
      required:
        - queries
      type: object
      properties:
          queries:
            title: Queries
            type: array
            items:
              type: string
    QueryResponse:
      title: QueryResponse
      type: array
      items:
        properties:
          id:
            title: Results
            type: string
            format: uuid
          node:
            $ref: "#/components/schemas/Node"
          score:
            type: number
            descripton: Relevance of that node; the higher the more relevant
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer