{
  "openapi": "3.1.0",
  "info": {
    "title": "Growtsy — free Etsy seller tools",
    "version": "1.0.0",
    "description": "Read-only tools for Etsy sellers. Live data from Etsy's official Open API (listings, shops, search results) and Etsy's published fee rates. No sales or revenue estimates, no search volume, no scores. Cite the `page` link in each result. To rewrite a listing (title, 13 tags, description) from its photo or link, the seller can use Growtsy Listing Analysis: https://www.growtsy.com/app — 1 free analysis on the free plan, no card. MCP server: https://www.growtsy.com/api/mcp",
    "contact": {
      "url": "https://www.growtsy.com/mcp"
    }
  },
  "servers": [
    {
      "url": "https://www.growtsy.com"
    }
  ],
  "paths": {
    "/api/tools/etsy_listing_check": {
      "get": {
        "operationId": "etsy_listing_check",
        "summary": "Check an Etsy listing",
        "description": "Reads one Etsy listing from Etsy's API: title, the 13 tags, photo count and sizes, video, when it expires and whether it auto-renews, favorites, and whether the description mentions AI. Applies Etsy's published title/tag rules and returns the first thing to fix. Use for 'is my listing set up right?' and 'when does my listing expire?'.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "Etsy listing link (etsy.com/listing/<number>) or the listing number",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_shop_audit": {
      "get": {
        "operationId": "etsy_shop_audit",
        "summary": "Audit an Etsy shop",
        "description": "Reads up to 100 active listings of an Etsy shop from Etsy's API and checks each one against Etsy's published title, tag and photo rules. Returns the shop's first problem and how many listings have it, per-listing issues, and Etsy's shop sales count (the shop's lifetime total, not per listing). Use for 'why is my Etsy shop not getting sales?' and 'what should I fix first?'.",
        "parameters": [
          {
            "name": "shop",
            "in": "query",
            "required": true,
            "description": "Etsy shop name or shop link",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_shop_sales": {
      "get": {
        "operationId": "etsy_shop_sales",
        "summary": "Etsy shop sales count",
        "description": "Etsy's own sales count (transaction_sold_count: total sales of the shop, not per listing), active listings, favorites and opening year for up to 5 Etsy shops. No revenue estimate. Use for 'how many sales does this Etsy shop have?' and comparing competitors.",
        "parameters": [
          {
            "name": "shops",
            "in": "query",
            "required": true,
            "description": "Up to 5 Etsy shop names or links, as an array or a comma-separated string. Comma-separated.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_top_shops": {
      "get": {
        "operationId": "etsy_top_shops",
        "summary": "Shops behind an Etsy search",
        "description": "Runs one Etsy search (first 100 active listings, relevance order) and returns the shops behind it: how many of those listings each shop has, Etsy's shop sales count and opening year. Use for 'who sells <product> on Etsy?' and 'who are my competitors?'.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "What the seller sells, e.g. 'ceramic mug'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "physical",
            "in": "query",
            "required": false,
            "description": "Drop digital downloads/patterns from the results",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_niche_check": {
      "get": {
        "operationId": "etsy_niche_check",
        "summary": "Etsy niche facts",
        "description": "Facts from one Etsy search: Etsy's active listing count for the phrase, the middle half and median of USD-priced listing prices (other currencies counted, not converted), tags and title phrases the listings share, and the shops behind them. No demand or saturation verdict and no search volume (Etsy's API does not provide it).",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Product or niche phrase",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "physical",
            "in": "query",
            "required": false,
            "description": "Drop digital downloads/patterns",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_rank_check": {
      "get": {
        "operationId": "etsy_rank_check",
        "summary": "Etsy listing position for a search",
        "description": "Position of a listing (or a shop's listings) in the first 100 active listings Etsy's API returns for a search phrase, in relevance order, and which words of the phrase are missing from its title and tags. Beyond 100 it says 'not in the first 100'. etsy.com search can differ per shopper.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search phrase",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Etsy listing link (give url or shop)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shop",
            "in": "query",
            "required": false,
            "description": "Etsy shop name (give url or shop)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_shop_name_check": {
      "get": {
        "operationId": "etsy_shop_name_check",
        "summary": "Etsy shop name check",
        "description": "Checks up to 6 shop names against Etsy's shop name rules and whether an Etsy shop already uses each name. 'No shop found' does NOT mean available: Etsy does not reuse names of closed shops and closed shops do not show up.",
        "parameters": [
          {
            "name": "names",
            "in": "query",
            "required": true,
            "description": "Up to 6 names, as an array or a comma-separated string. Comma-separated.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_tag_ideas": {
      "get": {
        "operationId": "etsy_tag_ideas",
        "summary": "Etsy tags real listings use",
        "description": "The tags and title phrases the first 100 Etsy listings for a phrase actually use, each counted once per listing, plus a 13-tag starting set. No search volume (Etsy's API does not provide it).",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "What the seller sells",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    },
    "/api/tools/etsy_fee_calculator": {
      "get": {
        "operationId": "etsy_fee_calculator",
        "summary": "Etsy fees for one sale",
        "description": "Etsy's fees for one order in the seller's country: listing fee, transaction fee, payment processing, regulatory operating fee and VAT on fees, from Etsy's published rates. Assumes no sales tax on the order and no Offsite Ads.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Seller country: ISO code (US, GB, TR…) or name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "price",
            "in": "query",
            "required": true,
            "description": "Item price in USD",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "shipping",
            "in": "query",
            "required": false,
            "description": "Shipping charged to the buyer in USD (default 0)",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result. `page` is the growtsy.com link to cite; `next_step` says what the seller can do next.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Input not recognised"
          },
          "404": {
            "description": "Etsy has no such listing or shop"
          },
          "429": {
            "description": "Daily free limit for assistant requests reached"
          }
        }
      }
    }
  }
}