lighting

Search the catalog of real products stocked by the suppliers on file. Accepts Persian or English. Returns normalized facets (mounting, indoor/outdoor, IP, colour temperature) plus what the query matched on. Colour temperature is returned but is NOT filterable: a fixture is usually sold in several, and the row carries the one its source printed. The response always reports what the filters excluded and why, split into 'not stated in our data' and 'did not match' — a product missing from a result is NEVER evidence that a supplier does not make it; use get_brand's doesNotDo for that.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free text in Persian or English, e.g. «چراغ خطی توکار» or 'recessed linear profile'."
    },
    "category": {
      "type": "string",
      "description": "One of the 20 canonical categories — see list_categories.",
      "enum": [
        "downlight",
        "wall",
        "magnetic",
        "linear",
        "pendant",
        "bollard",
        "ceiling-surface",
        "plaster-frame",
        "inground",
        "accessory",
        "track",
        "portable",
        "lamp",
        "street",
        "strip-profile",
        "industrial",
        "stair",
        "floodlight",
        "facade",
        "panel"
      ]
    },
    "brand": {
      "type": "string",
      "description": "Restrict to one supplier.",
      "enum": [
        "spl",
        "mazinoor",
        "nooran"
      ]
    },
    "environment": {
      "type": "string",
      "description": "indoor, outdoor, or both. 'indoor' also returns fixtures rated for both.",
      "enum": [
        "indoor",
        "outdoor",
        "both"
      ]
    },
    "mounting": {
      "type": "string",
      "description": "How it mounts.",
      "enum": [
        "inground",
        "magnetic",
        "track",
        "pendant",
        "semi-recessed",
        "recessed",
        "surface",
        "wall",
        "pole",
        "spike",
        "portable"
      ]
    },
    "ip_min": {
      "type": "integer",
      "description": "Minimum IP rating, e.g. 65 for a wet location.",
      "minimum": 20,
      "maximum": 69
    },
    "price_tier": {
      "type": "string",
      "description": "The price band the SUPPLIER declared for its whole range. Self-declared and per brand, not per product, and not a quoted price — no supplier on file publishes prices.",
      "enum": [
        "budget",
        "mid",
        "premium"
      ]
    },
    "has_image": {
      "type": "boolean",
      "description": "Only products with an image on file."
    },
    "limit": {
      "type": "integer",
      "description": "Results per page (default 20, max 50).",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset; use nextOffset from the previous call.",
      "minimum": 0,
      "maximum": 5000
    }
  },
  "additionalProperties": false
}

Every field on file for one product, by the id search_products returns ('brand/product-slug'), including provenance: whether the fact came from the supplier's own website or from a page of their PDF catalog, and when it was read.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Product id, e.g. 'spl/hangwire-puzzle-hangwire'."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

The 20 canonical categories with Persian and English names, product counts, and which suppliers are in each. Small enough to fetch once and reason over the whole market; flags categories that only one supplier covers.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Every supplier on file with what they cover, how complete their data is, and when it was last read. No contact details — see the server instructions.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

One supplier in full: what they make, the product families they run, and — the field worth the call — doesNotDo, a statement of what they genuinely do NOT make, computed from absence in their product list rather than inferred from their marketing.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Supplier slug from list_brands."
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false
}

Which suppliers cover a category, with counts, share, and per-facet data coverage. Coverage describes what each supplier's SOURCE stated, never product quality, and a one-supplier category says so rather than pretending to be a comparison.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "Category slug from list_categories.",
      "enum": [
        "downlight",
        "wall",
        "magnetic",
        "linear",
        "pendant",
        "bollard",
        "ceiling-surface",
        "plaster-frame",
        "inground",
        "accessory",
        "track",
        "portable",
        "lamp",
        "street",
        "strip-profile",
        "industrial",
        "stair",
        "floodlight",
        "facade",
        "panel"
      ]
    }
  },
  "required": [
    "category"
  ],
  "additionalProperties": false
}

Map any Persian or English lighting phrase onto the canonical taxonomy — «داون‌لایت توکار», 'trimless plaster frame', 'high bay'. Backed by 522 learned type→category pairs plus rules measured at 95% agreement. Returns null for a phrase that names no category rather than guessing.

{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "description": "A product type, in Persian or English."
    }
  },
  "required": [
    "term"
  ],
  "additionalProperties": false
}

Turn a described need into a link the person opens themselves, where an adviser builds a brief and matches it against suppliers' real stock. This is how someone actually reaches a supplier: there are no contact details in this server, and this call does not contact anyone. It stores nothing and it REFUSES any personal data — no name, no number, no email. Describe the project, not the person.

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "description": "The project in the person's own terms, in Persian or English — space, use, style, constraints. No personal details: the call is refused if it contains a phone number, an email or a handle."
    },
    "client": {
      "type": "string",
      "description": "Optional: a short name for your app, so we can tell which assistants send people here. Self-reported, lowercase slug."
    }
  },
  "required": [
    "need"
  ],
  "additionalProperties": false
}