# Explore a category

Understand a product category, its common specifications, available options and price distribution.

## What this endpoint does

Endpoint

```
POST https://mcp.gaisho.co/v1/tools/get_category_overview
```

Explore what matters when choosing a product type before looking for individual products. The overview describes common features, available options, approximate prices and retailer or brand differences. It is useful for turning a broad shopping question into a set of requirements.

- Explain which robot-vacuum features a shopper should compare.
- Explore air fryers that meet a capacity requirement.
- Compare a category by platform, price band or another supported dimension.

## Before you call

- Put the product type in category and requirements in conditions. For example, category can be air fryer while conditions says capacity at least 5 qt.
- Omit breakdown for the standard overview. Supply one dimension for a simple breakdown or two for a cross-comparison; use platform, retailer, price_band, brand_tier or brand. The overview does not publish a complete attribute-key mapping; put feature requirements in conditions rather than guessing a feature key.
- A category overview is about a product type. It does not return a shortlist of products or judge a particular quote.

Send a JSON object as the request body and authenticate with Authorization: Bearer <API key>. Amounts are in USD unless the result explicitly says otherwise.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| category | string | Required | Product type ID, category name, or a product ID or link. |
| conditions | string | Optional | Natural-language conditions for the category overview. |
| breakdown | string[] | Optional | One or two dimensions: platform, retailer, price_band, brand_tier or brand. Feature keys require a known category-specific key; the overview does not provide a complete mapping. Omit for the standard overview and express feature requirements in conditions. 1–2 items. |

## Example request

Set GAISHO_API_KEY in your server or local environment. These examples use a JSON POST request; Python uses the standard library and JavaScript uses Node.js fetch. The 60-second client timeout in Python and JavaScript is configurable, not a service latency guarantee.

cURL

```
curl --fail-with-body 'https://mcp.gaisho.co/v1/tools/get_category_overview' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "category": "robot vacuum"
}'
```

Python

```
import json
import os
import urllib.error
import urllib.request

arguments = json.loads(r'''{
  "category": "robot vacuum"
}''')
request = urllib.request.Request(
    "https://mcp.gaisho.co/v1/tools/get_category_overview",
    data=json.dumps(arguments).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["GAISHO_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        payload = json.load(response)
    print(json.dumps(payload, indent=2))
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8"))
    raise
```

JavaScript

```
// Node.js 18+; keep this code and the key on your server.
const response = await fetch("https://mcp.gaisho.co/v1/tools/get_category_overview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GAISHO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "category": "robot vacuum"
}),
  signal: AbortSignal.timeout(60_000),
});
const body = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const payload = JSON.parse(body);
console.log(payload);
```

## Common request patterns

### Explore a category with conditions

Keep the product type separate from the shopper’s requirements.

JSON request body

```
{
  "category": "air fryer",
  "conditions": "capacity at least 5 qt",
  "breakdown": [
    "platform",
    "price_band"
  ]
}
```

## Response fields

The HTTP response contains tool and summary. Product information is carried in summary text; there is no separate structured result array. Treat its wording as readable content, not a fixed column schema.

| Field | Type | Description |
| --- | --- | --- |
| tool | string | The tool called: get_category_overview. |
| summary | string | Category guidance, available specifications and requested breakdowns. |

## Example response

Examples are illustrative and may omit optional detail fields. Prices are not live quotes; identifiers and example.com URLs are placeholders to replace, not usable product records.

HTTP 200 · illustrative, shortened

```
{
  "tool": "get_category_overview",
  "summary": "Robot vacuums — category overview\nCommon features include navigation, mopping and automatic emptying.\nApproximate typical price: $300.\nAvailable options include vacuum-only models and models with a mopping function."
}
```

## How to read the result

- summary is a readable report, not a JSON array of categories. It may describe features, price levels, brand mix, platforms, feature notes and common return reasons, according to available information.
- Read the reported conditions to see which requirements were applied and which could not be applied. Do not treat an unresolved requirement as satisfied.
- Category prices are approximate context. Use search_products to find products and vet_price to assess a specified product and quote.

## Empty results and errors

| Situation | How to handle it |
| --- | --- |
| Category is unclear | Use a specific product type, such as cordless stick vacuum, rather than a broad department such as home. |
| A condition cannot be applied | Read the explanation and clarify that condition before describing the overview as fully filtered. |
| A feature breakdown is unavailable | Use a documented breakdown dimension, or put the feature requirement in conditions and omit breakdown. Display labels are not filter keys. |

A successful request can return no candidates, missing information or an unavailable assessment. Check the result before recommending a product. For request failures, use the error code and message; retrying the same invalid input will not fix it.

- [Error handling and retries](https://gaisho.co/docs/api#errors): HTTP statuses, structured errors, rate limits and quota responses.

## What to call next

- [Search products](https://gaisho.co/docs/api/search_products): Find products from shopping needs, keywords, a model or a product identifier.
- [Check a price](https://gaisho.co/docs/api/vet_price): Assess whether a USD price is reasonable for a stated product or shopping requirement.

- [Use this tool through MCP](https://gaisho.co/docs/mcp/get_category_overview): The same capability through the other connection.
- [REST API conventions](https://gaisho.co/docs/api): Authentication, response envelopes and request handling.