Gift Finder · Acciones GPT

GiftFinder Plugin API

A gift finder plugin API by VAFL for finding gifts for your loved ones. To start first determine if the user has some gift idea and wants to search for it (use /query endpoint) or if the user doesn't know what the gift should be and wants to get a list of gifts or gift ideas (use /generate_gift_v2).
POST /queryQuery for a specific gift idea or experience
Upon receiving a gift idea, always ask for budget in USD and location. Start a search based on city/country and budget. If an error, retry after 60 secs (max 2 attempts). If "data" is an empty list, reformulate the query and retry. Display suggestions with title, price, rating, and link.
POST /generate_gift_v2Generate personalised gift ideas
Used to suggest gifts / experiences, always request recipient's details, budget in USD, and location (if not provided). On error, retry twice. If "data" is empty, adjust query and retry. Display experiences, in a structured format with title, price, rating, link.
Esquema original API
{
  "openapi": "3.1.2",
  "info": {
    "title": "GiftFinder Plugin API",
    "description": "A gift finder plugin API by VAFL for finding gifts for your loved ones. To start first determine if the user has some gift idea and wants to search for it (use /query endpoint) or if the user doesn't know what the gift should be and wants to get a list of gifts or gift ideas (use /generate_gift_v2).",
    "instructionToAssistant": "Form URLs as https://vafl.me/query or https://vafl.me/generate_gift_v2. To determine the endpoint to call, start a conversation by asking or parsing whether user needs to search for something particular or needs suggestions and ideas. If user needs to search for something particular, call /query endpoint, if user needs suggestions and ideas, call /generate_gift_v2 endpoint.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://vafl.me"
    }
  ],
  "paths": {
    "/query": {
      "post": {
        "summary": "Query for a specific gift idea or experience",
        "description": "Upon receiving a gift idea, always ask for budget in USD and location. Start a search based on city/country and budget. If an error, retry after 60 secs (max 2 attempts). If \"data\" is an empty list, reformulate the query and retry. Display suggestions with title, price, rating, and link.",
        "operationId": "queryGifts",
        "x-openai-isConsequential": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPInteranlServerError"
                }
              }
            }
          }
        }
      }
    },
    "/generate_gift_v2": {
      "post": {
        "summary": "Generate personalised gift ideas",
        "description": "Used to suggest gifts / experiences, always request recipient's details, budget in USD, and location (if not provided). On error, retry twice. If \"data\" is empty, adjust query and retry. Display experiences, in a structured format with title, price, rating, link.",
        "operationId": "generateGiftsV2",
        "x-openai-isConsequential": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateGiftRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response. Returns a list of gift ideas with a list of experiences for each gift idea.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateGiftResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPInteranlServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    },
    "schemas": {
      "GenerateGiftRequest": {
        "title": "GenerateGiftRequest",
        "type": "object",
        "required": [
          "max_price",
          "country",
          "description"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Describe the person for whom you are searching a gift. Include age, occupation, hobbies, likes, etc."
          },
          "city": {
            "type": "string",
            "description": "City where the gift should be searched for. Leave blank if searching across the country."
          },
          "max_price": {
            "type": "number",
            "description": "Maximum price of the gift in USD."
          },
          "country": {
            "type": "string",
            "description": "Country where the gift should be searched for."
          }
        }
      },
      "GenerateGiftResponse": {
        "title": "GenerateGiftResponse",
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "instructionToAssistant": {
            "type": "string",
            "description": "Instruction to the assistant on how to output and refine the search results."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GiftIdeaGroup"
            }
          }
        }
      },
      "GiftIdeaGroup": {
        "title": "GiftIdeaGroup",
        "type": "object",
        "required": [
          "gift_idea",
          "gift_idea_description",
          "experiences"
        ],
        "properties": {
          "gift_idea": {
            "type": "string",
            "description": "General theme or category of the gift idea."
          },
          "gift_idea_description": {
            "type": "string",
            "description": "Description of why this gift idea suits the recipient."
          },
          "experiences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Experience"
            }
          }
        }
      },
      "Experience": {
        "title": "Experience",
        "type": "object",
        "required": [
          "titleEn",
          "price",
          "link"
        ],
        "properties": {
          "titleEn": {
            "type": "string",
            "description": "Title of the experience."
          },
          "price": {
            "type": "number",
            "description": "Price of the experience in USD."
          },
          "link": {
            "type": "string",
            "description": "Link to purchase or learn more about the experience."
          },
          "rating": {
            "type": "number",
            "description": "Average user rating of the experience."
          },
          "ratingCount": {
            "type": "number",
            "description": "Number of ratings the experience has received."
          }
        }
      },
      "QueryRequest": {
        "title": "QueryRequest",
        "type": "object",
        "required": [
          "query",
          "city",
          "max_price",
          "country"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Specific gift or type of experience being searched for."
          },
          "city": {
            "type": "string",
            "description": "City where the gift should be searched for."
          },
          "max_price": {
            "type": "number",
            "description": "Maximum price of the gift in USD."
          },
          "country": {
            "type": "string",
            "description": "Country where the gift should be searched for."
          }
        }
      },
      "QueryResponse": {
        "title": "QueryResponse",
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "instructionToAssistant": {
            "type": "string",
            "description": "Instruction to the assistant on how to output and refine the search results."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Experience"
            }
          }
        }
      },
      "HTTPValidationError": {
        "title": "HTTPValidationError",
        "type": "object",
        "properties": {
          "detail": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "ValidationError": {
        "title": "ValidationError",
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "properties": {
          "loc": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "msg": {
            "type": "string",
            "description": "A message explaining the error."
          },
          "type": {
            "type": "string",
            "description": "The type of error."
          }
        }
      }
    }
  }
}