{
  "openapi": "3.1.0",
  "info": {
    "title": "Effex Info: catalogue and answers",
    "version": "1.0.0",
    "description": "Read-only access to a daily snapshot of the catalogue of the Effex shop (effex.ee), an Estonian seller of electrical goods and materials with nine stores. No key. Prices are in euros and include VAT. Every product links to its page on the shop, which has the final word on price and stock. A search also returns the site's answers and guides that match the question (`articles`). Answers are cached for five minutes; a per-address rate limit applies. Also available: an MCP server at /mcp (streamable HTTP, stateless; tools search_products, get_product, list_categories, list_stores, search_answers, get_answer, get_company_info), feeds under /feeds/, every page as Markdown (add index.md to its address), /llms.txt and /llms-full.txt. A guide for people and assistants: /en/for-ai/."
  },
  "servers": [
    {
      "url": "https://info.effex.ee"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search product families, and the answers and guides, with a question or a few words (English or Estonian)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "description": "A question, a few words, a brand or a maker's code. Empty answers no items."
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "et",
                "ru",
                "fi"
              ],
              "default": "en"
            },
            "description": "Language of names and labels where the snapshot has them (en or et; ru and fi give English names), else Estonian. Articles in this language come first in articles, English ones after."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 24,
              "default": 10
            }
          },
          {
            "name": "hint",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Optional product line (e.g. \"Effex lighting\"): products in the categories that match it come first among equally good answers; a general name such as a shop name changes nothing."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching families, best first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this address.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/products/{id}": {
      "get": {
        "operationId": "getProduct",
        "summary": "One product family with its variants, prices, stock by store and the shop's addresses",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            },
            "description": "The shop's product family id."
          }
        ],
        "responses": {
          "200": {
            "description": "The family.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Not in the current snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "The category tree with family counts",
        "responses": {
          "200": {
            "description": "The tree.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryTree"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Spec": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "SearchItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The product's page on the shop."
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lowest price of the family's variants, EUR incl. VAT."
          },
          "currency": {
            "const": "EUR"
          },
          "price_includes_vat": {
            "const": true
          },
          "availability": {
            "type": "string",
            "enum": [
              "in_stock",
              "out_of_stock",
              "on_order",
              "unknown"
            ]
          },
          "summary": {
            "type": "string",
            "maxLength": 400
          },
          "specs": {
            "type": "array",
            "maxItems": 12,
            "items": {
              "$ref": "#/components/schemas/Spec"
            }
          },
          "seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "summary_lang": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "en",
              "et",
              null
            ],
            "description": "The language the summary is in; it can differ from the asked one."
          },
          "price_on_request": {
            "type": "boolean",
            "description": "The shop lists the product without a price; price is then null."
          }
        },
        "required": [
          "id",
          "name",
          "brand",
          "category",
          "url",
          "image",
          "price",
          "currency",
          "price_includes_vat",
          "availability",
          "summary",
          "specs",
          "seen_at",
          "summary_lang",
          "price_on_request"
        ]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "query": {
            "type": "string"
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "et"
            ]
          },
          "total": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchItem"
            }
          },
          "matched": {
            "$ref": "#/components/schemas/Matched"
          },
          "articles": {
            "type": "array",
            "maxItems": 5,
            "description": "The site's answers, guides and comparisons that match the question, the requested language's first, then English ones, each group best first (at most five). Separate from items and total, which count products only.",
            "items": {
              "$ref": "#/components/schemas/ArticleHit"
            }
          }
        },
        "required": [
          "generated_at",
          "query",
          "lang",
          "total",
          "items",
          "matched",
          "articles"
        ]
      },
      "ArticleHit": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The article's page on this site; add index.md for its Markdown."
          },
          "kind": {
            "type": "string",
            "enum": [
              "answer",
              "guide",
              "comparison"
            ]
          },
          "lang": {
            "type": "string",
            "enum": [
              "en",
              "et",
              "ru",
              "fi"
            ]
          },
          "verified": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "The day the article was last checked against its sources."
          },
          "matched_question": {
            "type": [
              "string",
              "null"
            ],
            "description": "The article's FAQ question that matches the search, when one does."
          }
        },
        "required": [
          "title",
          "url",
          "kind",
          "lang",
          "verified",
          "matched_question"
        ]
      },
      "Matched": {
        "type": "object",
        "description": "What the search recognised in the question, so that a reader can see why these products came back, or why none did. Products come only from the categories of the product phrases the question names (the head phrase decides; sizes, materials and places only rank inside them). A question that names no product (where to buy, which wholesaler, delivery) answers no items.",
        "properties": {
          "by": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "phrase",
              "name",
              "code",
              null
            ],
            "description": "phrase: product phrases were recognised; name: a product's own name, brand or category was typed; code: a maker's code or EAN; null: nothing recognised."
          },
          "phrases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The product phrases recognised, by their English names, the head phrases first, e.g. [\"cable tray\"]."
          },
          "categories": {
            "type": "array",
            "description": "The categories the items were drawn from.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            }
          }
        },
        "required": [
          "by",
          "phrases",
          "categories"
        ]
      },
      "Product": {
        "type": "object",
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "prices_as_of": {
            "type": "string",
            "format": "date-time"
          },
          "stock_as_of": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "sample_data": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "object",
            "properties": {
              "et": {
                "type": "string"
              },
              "en": {
                "type": "string"
              }
            },
            "required": [
              "et",
              "en"
            ]
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "object",
              "null"
            ]
          },
          "url": {
            "type": "object",
            "properties": {
              "et": {
                "type": "string"
              },
              "en": {
                "type": "string"
              }
            },
            "required": [
              "et",
              "en"
            ]
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": "object",
            "properties": {
              "et": {
                "type": "string"
              },
              "en": {
                "type": "string"
              }
            },
            "required": [
              "et",
              "en"
            ]
          },
          "summary_lang": {
            "type": "object",
            "description": "The language each summary text is in (en, et or null)."
          },
          "currency": {
            "const": "EUR"
          },
          "price_includes_vat": {
            "const": true
          },
          "vat_rate": {
            "type": "number"
          },
          "price_from": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_to": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_on_request": {
            "type": "boolean",
            "description": "The shop lists the product without a price."
          },
          "availability": {
            "type": "string",
            "enum": [
              "in_stock",
              "out_of_stock",
              "on_order",
              "unknown"
            ]
          },
          "stores_in_stock": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "town": {
                  "type": "string"
                }
              }
            }
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "code": {
                  "type": "string"
                },
                "ean": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "object",
                  "properties": {
                    "et": {
                      "type": "string"
                    },
                    "en": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "et",
                    "en"
                  ]
                },
                "price": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "price_ex_vat": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "unit": {
                  "type": "string"
                },
                "min_qty": {
                  "type": "number"
                },
                "clearance": {
                  "type": "boolean"
                },
                "availability": {
                  "type": "string",
                  "enum": [
                    "in_stock",
                    "out_of_stock",
                    "on_order",
                    "unknown"
                  ]
                },
                "stock": {
                  "type": [
                    "object",
                    "null"
                  ]
                }
              }
            }
          },
          "changed": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "generated_at",
          "id",
          "name",
          "url",
          "currency",
          "availability",
          "variants"
        ]
      },
      "CategoryTree": {
        "type": "object",
        "properties": {
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "generated_at",
          "categories"
        ]
      }
    }
  }
}
