{
  "openapi": "3.1.0",
  "info": {
    "title": "Seller2Buyer API",
    "version": "1.1.0",
    "summary": "What is for sale, at what price, is it in stock, and which shop sells it?",
    "description": "Read API, no key. The same data the pages show. Each seller's ID is checked before the shop goes public. Titles, descriptions, prices and stock are each seller's own words and numbers, and they change at any time: fetch them, and say when you fetched. Prices are in Philippine pesos (PHP).",
    "license": {
      "name": "RSL 1.0",
      "url": "https://seller2buyer.aplusz.app/license.xml"
    },
    "x-llms-txt": "https://seller2buyer.aplusz.app/llms.txt"
  },
  "servers": [
    {
      "url": "https://seller2buyer.aplusz.app"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchListings",
        "summary": "Is there a listing for what the person is looking for?",
        "description": "Returns item ids only. `exact`: every word found in the title, description, category, shop or city. `similar`: close items, listed when there are 3 exact matches or fewer. `fallback: true` means nothing matched and the newest items stand in: do not present those as matches. Read each item's price, stock and shop from /api/catalog.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "What the person is looking for, in plain words, up to 120 characters. Example: seiko automatic watch. An empty q returns two empty lists.",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "example": "seiko automatic watch"
          },
          {
            "name": "c",
            "in": "query",
            "required": false,
            "description": "Category id to stay inside. One of: watches, phones, fashion, food, home, rides, outdoors, plants, kids, beauty, books, crafts, music, tools. Leave out to search every category. A category name in words is not an id.",
            "schema": {
              "type": "string",
              "enum": [
                "watches",
                "phones",
                "fashion",
                "food",
                "home",
                "rides",
                "outdoors",
                "plants",
                "kids",
                "beauty",
                "books",
                "crafts",
                "music",
                "tools"
              ]
            },
            "example": "watches"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching item ids.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "listCatalog",
        "summary": "What is for sale right now, at what price, and is it in stock?",
        "description": "Every public listing and shop, in pages. offset 0 is the newest page; inside a page the newest item comes last. `shops` comes with offset 0 only. `more: true` means another page follows at offset + limit. Always pass limit: without limit the whole catalog is sent in one answer.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 500. Example: 300.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            },
            "example": 300
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "How many of the newest items to skip. Example: 0, then 300, then 600. Only read together with limit.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogPage"
                }
              }
            }
          }
        }
      }
    },
    "/api/shop/{id}/reviews": {
      "get": {
        "operationId": "getShopReviews",
        "summary": "How do buyers rate this shop?",
        "description": "The shop's average stars, the number of reviews and the 20 newest reviews. A shop with no review yet returns avg 0 and n 0, which means not rated, not badly rated.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The shop id: `shopId` on an item, `id` on a shop in /api/catalog. A shop name is not an id.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stars and reviews.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShopReviews"
                }
              }
            }
          }
        }
      }
    },
    "/api/item/{id}/reviews": {
      "get": {
        "operationId": "getItemReviews",
        "summary": "How do buyers rate this item?",
        "description": "The item's own average stars, the number of its reviews and its 20 newest reviews (the shop's other items not counted). An item with no review yet returns avg 0 and n 0. An item no longer listed returns 404.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The item id: `id` on an item in /api/catalog.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stars and reviews.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShopReviews"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Is the marketplace up?",
        "responses": {
          "200": {
            "description": "Running."
          },
          "503": {
            "description": "Something is wrong; the body names it."
          }
        }
      }
    },
    "/facts.json": {
      "get": {
        "operationId": "getFacts",
        "summary": "What is true about this site, and how can each claim be checked?",
        "responses": {
          "200": {
            "description": "Facts packet",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getSummary",
        "summary": "Which questions does this site answer, and where is each answer fetched?",
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {}
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getFullText",
        "summary": "What do the answers guarantee, what does each field mean, how is the site cited?",
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {}
            }
          }
        }
      }
    },
    "/{lang}/index.md": {
      "get": {
        "operationId": "getPageMarkdown",
        "summary": "What is this site, as text, in one language?",
        "parameters": [
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "ar",
                "cs",
                "da",
                "de",
                "es",
                "fil",
                "fr",
                "hi",
                "id",
                "it",
                "ja",
                "ko",
                "ms",
                "nl",
                "no",
                "pl",
                "pt",
                "ro",
                "sv",
                "th",
                "tr",
                "vi",
                "zh-Hans",
                "zh-Hant"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Item": {
        "type": "object",
        "required": [
          "id",
          "title",
          "pricePhp",
          "stock",
          "shopId"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The id in the item address /item/{id}/."
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "The seller's own words."
          },
          "category": {
            "type": "string",
            "enum": [
              "watches",
              "phones",
              "fashion",
              "food",
              "home",
              "rides",
              "outdoors",
              "plants",
              "kids",
              "beauty",
              "books",
              "crafts",
              "music",
              "tools"
            ]
          },
          "condition": {
            "type": "string",
            "description": "The seller's own words."
          },
          "pricePhp": {
            "type": "number",
            "description": "Price of one, in Philippine pesos (PHP)."
          },
          "stock": {
            "type": "integer",
            "description": "How many are left. 0 means sold out."
          },
          "shopId": {
            "type": "string",
            "description": "The shop that sells the item."
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Photo paths under https://seller2buyer.aplusz.app."
          },
          "rating": {
            "type": "object",
            "description": "The item's own stars from buyers of this item (absent until its first review). Details: /api/item/{id}/reviews.",
            "properties": {
              "avg": {
                "type": "number",
                "description": "Average stars, 1 to 5."
              },
              "n": {
                "type": "integer",
                "description": "Number of reviews."
              }
            }
          }
        }
      },
      "Shop": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The id in the shop address /shop/{id}/."
          },
          "name": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "sells": {
            "type": "string",
            "description": "What the shop sells, in the seller's words."
          },
          "delivery": {
            "description": "The ways the shop delivers."
          },
          "joined": {
            "description": "When the shop joined."
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "exact",
          "similar"
        ],
        "properties": {
          "exact": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Item ids."
          },
          "similar": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Item ids."
          },
          "fallback": {
            "type": "boolean",
            "description": "True when nothing matched and the newest items stand in."
          }
        }
      },
      "CatalogPage": {
        "type": "object",
        "required": [
          "items",
          "shops"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "shops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shop"
            }
          },
          "total": {
            "type": "integer",
            "description": "Public listings in all."
          },
          "more": {
            "type": "boolean",
            "description": "True when another page follows."
          }
        }
      },
      "ShopReviews": {
        "type": "object",
        "required": [
          "avg",
          "n",
          "list"
        ],
        "properties": {
          "avg": {
            "type": "number",
            "description": "Average stars, 1 to 5. 0 with n 0: not rated yet."
          },
          "n": {
            "type": "integer",
            "description": "Number of reviews."
          },
          "list": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "The 20 newest."
          }
        }
      }
    }
  }
}
