openapi: 3.0.0
info:
  title: Proompty
  version: 1.1.0
  description: |2-

    Proompty is an advanced Retrieval Augmented Generation (RAG) API designed
    to empower users in seamlessly integrating their data and harnessing the
    power of customized Large Language Model (LLM) prompts for interactive
    communication. At its core, Proompty operates through a series of
    interconnected functionalities that enable users to navigate and
    manipulate their data effectively.
  termsOfService: https://proompty.com/terms-of-service
  contact:
    email: developers@proompty.com
externalDocs:
  url: /api.yaml
  description: OpenAPI Specification
servers:
  - url: https://app.proompty.com/api
security:
  - APIKey: []
tags:
  - name: Chat
  - name: Documents
  - name: Me
  - name: Prompt
  - name: Prompts
  - name: Topic
  - name: Topics
  - name: Uploads
  - name: User
    description: User related endpoints
paths:
  /me:
    get:
      tags:
        - Me
        - User
      description: Retrieve user information
      summary: >-
        Retrieves user information within the Proompty API system. By sending a
        GET request to this endpoint, users can obtain detailed data pertaining
        to their profile and associated claims. This includes essential user
        attributes such as email, full name, avatar URL, subscription plan, and
        role. Additionally, the response includes claims regarding the user's
        subscription status, role type, and other pertinent details. In the
        event that the requested user is not found, a 404 error response is
        returned, indicating the absence of the specified user within the
        system.
      responses:
        '200':
          description: User info
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/User'
                properties:
                  claims:
                    $ref: '#/components/schemas/Claims'
        '404':
          description: User not found
  /topics/{topicId}:
    get:
      tags:
        - Topic
        - Topics
      description: Get a topic by ID
      summary: >-
        Retrieve details about a specific topic in the Proompty API. By sending
        a GET request to this endpoint with the corresponding topicId parameter,
        users can access information such as the topic's title, description, and
        any associated documents or chats. The API responds with the topic
        object in JSON format, containing the relevant details. In case the
        requested topic is not found, appropriate error responses are returned
        (404 for topic not found, 500 for other errors), ensuring users receive
        accurate feedback regarding the status of their request.
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: query
          name: include
          schema:
            type: string
          required: false
          description: >-
            Include additional data in the response. Possible values: documents,
            chats.
      responses:
        '200':
          description: Topic
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'
        '404':
          description: Not found
    put:
      tags:
        - Topic
        - Topics
      description: Update a topic by ID
      summary: >-
        Update the details of a specific topic in the Proompty API. By sending a
        PUT request to this endpoint with the corresponding topicId parameter
        and the updated topic object in the request body, users can modify the
        topic's title, description, or other attributes. The API responds with
        the updated topic object in JSON format, containing the new details. In
        case the requested topic is not found, an appropriate error response is
        returned (404), ensuring users receive accurate feedback regarding the
        status of their request.
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Topic'
      responses:
        '200':
          description: Topic
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'
  /topics/{topicId}/documents/{documentId}:
    get:
      tags:
        - Documents
        - Topic
        - Topics
      description: Get a document by ID
      summary: >-
        Retrieve details about a specific document within a designated topic in
        the Proompty API. By sending a GET request to this endpoint with the
        corresponding topicId and documentId parameters, users can access
        information such as the document's content, creation date, and any
        associated metadata. The API responds with the document object in JSON
        format, containing the relevant details. In case the requested document
        or topic is not found, appropriate error responses are returned (404 for
        document not found, 500 for other errors), ensuring users receive
        accurate feedback regarding the status of their request.
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: documentId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          description: Not found
    delete:
      tags:
        - Documents
        - Topic
        - Topics
      description: Delete a document by ID
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: documentId
          schema:
            type: string
          required: true
      responses:
        '200':
          description: ok
        '404':
          description: Not found
      summary: >-
        Delete a specific document within a designated topic in the Proompty
        API. Users can send a DELETE request to this endpoint with the relevant
        topicId and documentId parameters to remove the specified document from
        the topic. The API responds with a success message in JSON format,
        confirming that the document has been successfully deleted. In case the
        requested document or topic is not found, appropriate error responses
        are returned (404 for document not found, 500 for other errors),
        ensuring users receive accurate feedback regarding the status of their
        request.
  /topics/{topicId}/documents/upload:
    post:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
      tags:
        - Documents
        - Topic
        - Topics
        - Uploads
      description: Upload a document to a topic
      summary: >-
        Upload a document to a specific topic. Users can send a POST request to
        this endpoint with the relevant topicId parameter and a document file to
        upload a new document to the specified topic. The API responds with a
        JSON object containing the uploaded document details and any relevant
        metadata. This endpoint enables users to efficiently upload and manage
        documents within topics, facilitating seamless access and sharing of
        resources across the Proompty platform. In case the document already
        exists within the specified topic, the endpoint returns an appropriate
        error response (409), indicating that the document is already present in
        the topic.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: Document uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    $ref: '#/components/schemas/Document'
        '404':
          description: Topic not found
        '409':
          description: Document already exists
        '500':
          description: Error uploading document
  /topics/{topicId}/prompts/{promptId}/chat:
    post:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: promptId
          schema:
            type: string
          required: true
      tags:
        - Chat
        - Prompt
        - Prompts
        - Topic
        - Topics
      description: >
        Chat with a Prompt AI with a message or a binary stream using
        content-type: application/octet-stream (see Request body dropdown)
      summary: >
        Retrieves user information within the Proompty API system. By sending a
        GET request to this endpoint, users can obtain detailed data pertaining
        to their profile and associated claims. This includes essential user
        attributes such as email, full name, avatar URL, subscription plan, and
        role. Additionally, the response includes claims regarding the user's
        subscription status, role type, and other pertinent details. In the
        event that the requested user is not found, a 404 error response is
        returned, indicating the absence of the specified user within the
        system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                message:
                  type: string
                  description: The message to send to the prompt AI.
                  example: What is your favorite color?
                model:
                  type: string
                  description: The model to use for the response. Default is gpt4.
                  example: gpt3 | gpt4 | gpt4o
                temperature:
                  type: string
                  description: The temperature to use for the response. Default is 0.15.
                  example: '0.15'
                maxTokens:
                  type: string
                  description: >-
                    The maximum number of tokens to generate for the response.
                    Default is 500.
                  example: '500'
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: The binary stream to be uploaded.
      responses:
        '200':
          description: Prompt
          content:
            application/json:
              schema:
                properties:
                  text:
                    type: string
                    description: The response from the prompt AIt.
                    example: My favorite color is blue.
                  model:
                    type: string
                    description: The model used to generate the response.
                    example: gpt4
                  sourceDocuments:
                    type: array
                    items:
                      type: object
                      properties:
                        metadata:
                          type: object
                          properties:
                            documentId:
                              type: string
                            filename:
                              type: string
                            topicId:
                              type: string
        '404':
          description: Prompt not found
        '500':
          description: Error getting prompt
  /topics/{topicId}/prompts/{promptId}:
    get:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: promptId
          schema:
            type: string
          required: true
      tags:
        - Prompt
        - Prompts
        - Topic
        - Topics
      description: Retrieves a Prompt
      summary: >-
        Retrieve details about a specific prompt within a designated topic in
        the Proompty API. By sending a GET request to this endpoint with the
        corresponding topicId and promptId parameters, users can access
        information such as the prompt's content, creation date, and any
        associated metadata. The API responds with the prompt object in JSON
        format, containing the relevant details. In case the requested prompt or
        topic is not found, appropriate error responses are returned (404 for
        prompt not found, 500 for other errors), ensuring users receive accurate
        feedback regarding the status of their request.
      responses:
        '200':
          description: Prompt
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Prompt'
        '404':
          description: Prompt not found
        '500':
          description: Error getting prompt
    put:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: promptId
          schema:
            type: string
          required: true
      tags:
        - Prompt
        - Prompts
        - Topic
        - Topics
      description: Update a Prompt
      summary: >-
        Proompty Update a specific prompt within a designated topic. Users can send a PUT request to this endpoint with the corresponding topicId and promptId parameters, along with a JSON payload containing the updated prompt information. This enables users to modify aspects of the prompt such as its content, metadata, or any other relevant properties. Upon successful execution, the endpoint responds with the updated prompt object in JSON format, providing confirmation of the changes made. In case the specified prompt or topic is not found, the endpoint returns an appropriate error response (404 for prompt not found, 500 for other errors), ensuring transparent communication and accurate handling of requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Prompt'
      responses:
        '200':
          description: Prompt
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Prompt'
        '404':
          description: Prompt not found
        '500':
          description: Error getting prompt
    delete:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
        - in: path
          name: promptId
          schema:
            type: string
          required: true
      tags:
        - Prompt
        - Prompts
        - Topic
        - Topics
      description: Deletes a Prompt
      summary: >-
        Remove a specific prompt associated with a particular topic. To utilize
        this endpoint, users send a DELETE request with the relevant topicId and
        promptId parameters. Upon successful execution, the specified prompt is
        permanently deleted from the system. The API responds with a
        confirmation message indicating the successful deletion of the prompt.
        In the event that the requested prompt or topic is not found,
        appropriate error responses are returned (404 for prompt not found, 500
        for other errors). This endpoint provides users with the capability to
        manage prompts effectively within their topics, ensuring streamlined
        content management within the Proompty platform.
      responses:
        '200':
          description: Confirmation
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Prompt deleted
        '404':
          description: Prompt not found
        '500':
          description: Error getting prompt
  /topics/{topicId}/prompts:
    get:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
      tags:
        - Prompts
        - Topic
        - Topics
      description: Retrieve all prompts for a topic
      summary: >-
        Retrieve a list of all prompts associated with a specific topic. Users
        can send a GET request to this endpoint with the relevant topicId
        parameter to access comprehensive information about each prompt within
        the specified topic. The API responds with an array of prompt objects in
        JSON format, containing details such as prompt content, creation dates,
        and any relevant metadata. This endpoint facilitates efficient
        management and retrieval of prompts within topics, allowing users to
        access and utilize prompts effectively in their interactions with the
        Proompty platform. In case the requested topic is not found, the
        endpoint returns an appropriate error response (404), ensuring clarity
        and accuracy in communication between users and the API.
      responses:
        '200':
          description: Prompts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Prompt'
        '404':
          description: Topic not found
        '500':
          description: Error getting prompts
    post:
      parameters:
        - in: path
          name: topicId
          schema:
            type: string
          required: true
      tags:
        - Prompts
        - Topic
        - Topics
      description: Create a prompt for a topic
      summary: >-
        Create a new prompts within a specified topic. Users can send a POST
        request to this endpoint, including the topicId parameter in the URL
        path and a JSON payload containing the details of the prompt to be
        created. This payload typically includes the prompt content, along with
        any relevant metadata. Upon successful execution, the API responds with
        the newly created prompt object in JSON format, confirming its addition
        to the specified topic. If there are any issues with the request, such
        as invalid input data or the specified topic not being found, the
        endpoint returns an appropriate error response (400 for bad request, 404
        for topic not found), ensuring users receive accurate feedback regarding
        the status of their request. This endpoint offers users a
        straightforward method for adding prompts to topics, facilitating the
        efficient management and organization of content within the Proompty
        platform.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Prompt'
      responses:
        '200':
          description: Prompt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: Bad request
        '404':
          description: Topic not found
        '500':
          description: Error creating prompt
  /topics:
    get:
      tags:
        - Topics
      description: Get all topics
      summary: >-
        Retrieve all topics in the Proompty API. By sending a GET request to
        this endpoint, users can access a list of all topics available in the
        system. The API responds with an array of topic objects in JSON format,
        containing the relevant details. In case no topics are found, an
        appropriate error response is returned (404), ensuring users receive
        accurate feedback regarding the status of their request.
      parameters:
        - in: query
          name: include
          schema:
            type: string
          required: false
          description: 'Include additional data in the response. Possible values: chats.'
      responses:
        '200':
          description: Topic[]
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Topic'
        '404':
          description: Not found
    post:
      tags:
        - Topics
      description: Create a topic
      summary: >-
        Create a new topic in the Proompty API. By sending a POST request to
        this endpoint with the new topic object in the request body, users can
        create a new topic with the specified attributes. The API responds with
        the newly created topic object in JSON format, containing the relevant
        details. In case the maximum number of topics allowed on the user's plan
        is reached, an appropriate error response is returned (400), ensuring
        users receive accurate feedback regarding the status of their request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Topic'
      responses:
        '200':
          description: Topic
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'
        '400':
          description: Maximum topics reached
        '500':
          description: Internal server error