# Get product details

Read product specifications, ratings, reviews and offers, for one product or up to eight at once.

## What this endpoint does

Endpoint

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

Research a selected product and compare its specifications, ratings, reviews and purchase offers. A product can have several listings from different sellers or retailers. This endpoint brings those details together so the shopper can decide which product to investigate further.

- Read the specifications and offers for a product found by search.
- Request details for a shortlist of up to eight products together.
- Include alternative models, specification upgrades or downgrades, or additional product checks.

## Before you call

- Use product for one item or products for a batch, rather than sending both. A batch accepts one to eight entries and answers them in the supplied order. If both are sent, a non-empty products array takes precedence and product is ignored.
- Prefer product IDs returned by search when available. Product URLs, ASINs, GTINs, model numbers and short descriptions are also accepted; pass a URL or ID alone.
- include applies to every item in the request. Use dupes for alternative models, ladder for specification changes, and checkup for additional checks. Omit it when ordinary product details are enough.

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 |
| --- | --- | --- | --- |
| product | string | One of these required | Product URL, ASIN, GTIN, ID, model or description. Pass URLs and IDs alone. |
| products | string[] | One of these required | Products to request together, instead of product. Each item takes the same values as product. 1–8 items. |
| include | string[] | Optional | dupes: alternative models; ladder: specification upgrades and downgrades; checkup: additional product checks. Any of: dupes, ladder, checkup. |

## 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_product' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "product": "PRODUCT_ID_FROM_SEARCH"
}'
```

Python

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

arguments = json.loads(r'''{
  "product": "PRODUCT_ID_FROM_SEARCH"
}''')
request = urllib.request.Request(
    "https://mcp.gaisho.co/v1/tools/get_product",
    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_product", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GAISHO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "product": "PRODUCT_ID_FROM_SEARCH"
}),
  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

### Research two products together

Replace both placeholders with IDs returned by search.

JSON request body

```
{
  "products": [
    "PRODUCT_ID_FROM_SEARCH",
    "SECOND_PRODUCT_ID_FROM_SEARCH"
  ]
}
```

### Include alternative models

Request the extra section only when it is relevant to the shopper.

JSON request body

```
{
  "product": "PRODUCT_ID_FROM_SEARCH",
  "include": [
    "dupes"
  ]
}
```

## 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_product. |
| summary | string | Requested product details, offer identifiers and any additional comparisons. |

## 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_product",
  "summary": "Example cordless vacuum\nproduct_id: PRODUCT_ID_FROM_SEARCH\nBattery runtime: 40 minutes\nRating: 4.5 out of 5\nOffer: OFFER_ID_FROM_SEARCH — $179.99, Example Store\nPurchase link: https://example.com/vacuum"
}
```

## How to read the result

- summary contains the requested product details and offers as text. The public endpoint does not return separate product or offers JSON fields.
- The product is the shared model; each offer has its own seller, price and purchase link. Use the relevant offer_id when the question concerns a listing or its terms.
- Treat omitted specifications, ratings or reviews as unavailable information. Do not infer a warranty, accessory or compatibility claim from the product name alone.

## Empty results and errors

| Situation | How to handle it |
| --- | --- |
| The description could identify several models | Search first and pass the chosen product_id, or provide an exact model or product URL. |
| A listing-specific detail is missing | Call get_offer for the selected listing, especially for warranty, shipping, returns or what is included. |
| More than eight products | Narrow the shortlist or split it into batches of at most eight. |

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

- [Get offer details](https://gaisho.co/docs/api/get_offer): Read a listing’s purchase URL, seller, price, coupon terms and stated product information.
- [Check a price](https://gaisho.co/docs/api/vet_price): Assess whether a USD price is reasonable for a stated product or shopping requirement.
- [Compare purchase options](https://gaisho.co/docs/api/find_deals): Find offers for the same product, compatible alternatives, or models with specification upgrades and downgrades.

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