{
  "openapi": "3.1.0",
  "info": {
    "title": "Uneed read API",
    "version": "1.0.0",
    "description": "Read-only API over uneed.best product data: search, product profiles, alternatives, community rankings, recent launches, deals and categories. The same contract is served as a remote MCP server (Streamable HTTP) at https://mcp.uneed.best/mcp — prefer MCP if your agent supports it. No authentication in v1; per-IP rate limits apply.",
    "contact": {
      "url": "https://www.uneed.best"
    }
  },
  "servers": [
    {
      "url": "https://mcp.uneed.best"
    }
  ],
  "paths": {
    "/v1/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Full-text product search (typo-tolerant, over names, descriptions and tags)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search terms"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products with relevance rank"
          }
        }
      }
    },
    "/v1/products/{slug}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Full product profile: details, tags, deals and community stats (aggregates only)",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A product listed on uneed.best (public projection)",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "rich_description": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "url": {
                      "type": "string",
                      "description": "The product's own website"
                    },
                    "uneed_url": {
                      "type": "string",
                      "description": "The product page on uneed.best"
                    },
                    "logo": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "images": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "string"
                      }
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "pricing": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "rate": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Average community rating"
                    },
                    "premium": {
                      "type": "boolean",
                      "description": "True when the product pays for featured placement (disclosure)"
                    },
                    "launch_date": {
                      "type": "string",
                      "format": "date"
                    },
                    "created_at": {
                      "type": "string"
                    },
                    "twitter": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "bluesky": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "linkedin": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "github": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "instagram": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "facebook": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "youtube": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/v1/products/{slug}/alternatives": {
      "get": {
        "operationId": "getAlternatives",
        "summary": "Alternatives scored by weighted tag overlap, with the shared tags explaining each match",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scored alternatives"
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/v1/trending": {
      "get": {
        "operationId": "getTrending",
        "summary": "Community-voted rankings of products launched in a period (ISO weeks, America/Los_Angeles anchored)",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "daily",
                "weekly",
                "monthly",
                "yearly"
              ]
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "Any date inside the wanted period (YYYY-MM-DD); omit for the current period",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked products with summed vote value"
          }
        }
      }
    },
    "/v1/launches": {
      "get": {
        "operationId": "getRecentLaunches",
        "summary": "Most recent launches, newest first, filterable by category and tag",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug or exact name (see /v1/categories)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Tag slug"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent launches"
          }
        }
      }
    },
    "/v1/deals": {
      "get": {
        "operationId": "listDeals",
        "summary": "Active promo deals (discount codes and offers) with the product they apply to",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug or exact name (see /v1/categories)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Active deals"
          }
        }
      }
    },
    "/v1/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "Product categories with slug and product count",
        "responses": {
          "200": {
            "description": "Categories"
          }
        }
      }
    }
  }
}