openapi: "3.0.1"
info:
  title: Bestever
  description: Bestever converts your product references into captivating image ads. Our AI scripts, polishes your visuals, and generates amazing results!
  version: "0.1"
servers:
  - url: https://chatgpt-plugin-7npmcik6ca-uc.a.run.app
paths:
  /suggestions:
    post:
      summary: Get suggestions for the plugin
      operationId: suggestions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                suggestion:
                  type: string
                  description: The suggestion given by the user, for later reference by the developers
                image_inspiration_url:
                  type: string
                  description: The url of the image that inspired the user to make the suggestion, or the url of a reference advert that serves as the inspiration for the requested ad
                email:
                  type: string
                  description: The email of the user, for later reference by the developers
      responses:
        '204':
          description: No Content
  /fetch:
    post:
      summary: Search for product images. Returns images user can choose from to create ad. If this fails, user can provide their own image link, product name and description instead.
      operationId: fetch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The product page URL. A product listing should be provided here, amazon is preferred. But others might be supported in the future.
                platform:
                  type: string
                  enum: [chatgpt-plugin, bestever-gpt]
                  default: chatgpt-plugin
                  description: Always required. Whether the chatgpt-plugin or the custom Bestever GPT is generating this ad
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchResponse'

  /generate:
    post:
       summary: Generate an ad, or retry if previous request fails or user unhappy with quality. If unhappy, they can provide their own image, product name and product description for better quality results. Also, prompt user always for the reference image url that served as inspiration for the request.
       operationId: newAd
       requestBody:
         required: true
         content:
           application/json:
             schema:
              $ref: '#/components/schemas/StartProjectGeneration'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
                type: object
                properties:
                  url:
                    type: string
                    description: Generated image ad url
                  hint:
                    type: string
                    description: A hint to the user on how to improve the generated ad
                  edit_url:
                    type: string
                    description: If empty, skip it. Or else, provide it to the user always specifying that it is a URL if they want to edit further and make some changes to the ad, and they will not be able to edit it anymore with the plugin. URL will contain important query params, so don't escape any characters in this URL!
         '400':
            description: Bad Request
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    error:
                      type: string
                      description: The error message, if it says the project is claimed by user, tell the user they can create a new project or use the link above to edit the project, if there does exist a link

components:
  schemas:
    FetchedAssetSummary:
      type: object
      properties:
        image_url:
          type: string
          description: The url of the image
        asset_id:
          type: string
          description: The id of the image, to be used as reference when the user chooses which he wants to use
    FetchResponse:
      type: object
      properties:
        image_choices:
          type: array
          items:
            $ref: '#/components/schemas/FetchedAssetSummary'
          description: A list of images the user must choose from in order to create an ad. Currently, only one can be chosen
    StartProjectGeneration:
      type: object
      properties:
        project_id:
          type: string
          description: The project UUID of project generated from the /fetch call
        chosen_asset_id:
          type: string
          description: The asset UUID chosen by the user from the list of images shown to the user from the previous step. This must only be one that they choose, or empty uuid if the user provided their own image
        product_name:
          type: string
          description: If the user is disatisfied with the fetching and provided their own product name, this will be the product name they provided. This is optional if they provide it, or else it will be empty.
        product_description:
          type: string
          description: If the user is disatisfied with the fetching and provided their own product description, this will be the product description they provided and must be greater than 70 characters. This is optional if they provide it, or else it will be empty.
        image_url:
          type: string
          description: The url of the image provided by the user if they provided their own image
        image_inspiration_url:
          type: string
          description: The url of the image that inspired the user to make the suggestion, or the url of a reference advert that serves as the inspiration for the requested ad. This is optional if they provide it, or else it will be empty. Prompt it always.
        should_wait:
          type: boolean
          description: Always required. Whether the user wants to wait for project to all assets and project to come out of preprocessing. False if the user wants to skip, true in all other cases. Must be provided in all cases.
          default: true
        is_first_call_to_generate:
          type: boolean
          description: Always required. Set to false if generate has been called at least one time before
          default: true
        platform:
          type: string
          enum: [chatgpt-plugin, bestever-gpt]
          default: chatgpt-plugin
          description: Always required. Whether the chatgpt-plugin or the custom Bestever GPT is generating this ad