# REST API

Call gaisho from your application or scripts with authenticated JSON requests.

## Authentication

Send your API key in the Authorization header on every request. Create and manage keys in the console. Keep credentials on the server.

Header

```
Authorization: Bearer <API key>
```

- [Manage API keys](https://app.gaisho.co/console): Open your gaisho console.

## Requests

| Method | Path | Purpose |
| --- | --- | --- |
| GET | /v1/tools | Discover current tool names and input schemas. |
| POST | /v1/tools/{tool} | Call a tool with a JSON object as its body. |

Base URL

```
https://mcp.gaisho.co/v1
```

Use Content-Type: application/json. Send the tool arguments directly as the body, not inside a tool, arguments or JSON-RPC wrapper. The endpoint pages use POST consistently, including for arrays and nested objects.

Use numbers for prices and quantities, booleans for flags and JSON arrays for batches. Omit an optional field when it is not known; do not send an empty string, zero or a guessed value instead.

Example request

```
curl --fail-with-body 'https://mcp.gaisho.co/v1/tools/vet_price' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "product": "Bose QuietComfort Ultra Headphones (2nd Gen)",
  "price": 349
}'
```

## Products, offers and quantities

| Value | Meaning | How to use it |
| --- | --- | --- |
| product_id | A product or model | Pass to product research, price checks or purchase comparisons. |
| offer_id | One listing for a product | Pass to listing details; keep its seller, price and URL together. |
| image_id | A previously submitted image | Reuse in image search during its 30-day retention period. |
| price + unit | A total price and the quantity it covers | For two 500 ml bottles costing $18 total, use price 18 and quantity 1000 ml. |

Use identifiers actually returned by gaisho. Example IDs and example.com links in these docs are placeholders. When passing an identifier or URL, send it alone; put requirements in the field documented for that tool.

## Response envelopes

HTTP 200 means the request was processed. The payload can still report no matches, an ambiguous identity, missing information or an unavailable assessment. Read the tool-specific result before presenting a recommendation.

| Tools | Top-level fields | Where the answer is |
| --- | --- | --- |
| get_category_overview, search_products, get_product, get_offer | tool, summary | Readable text in summary; no separate result array. |
| vet_price | tool, summary, result | Explanation in summary; verdict, action, confidence and evidence in result. |
| find_deals | tool, summary, result | Readable coverage in summary; purchase options and comparison details in result. |
| vet_seller, search_products_by_image | tool, result | The complete tool payload in result, including its own summary if provided. |

Illustrative response · not a live quote

```
{
  "tool": "vet_price",
  "summary": "$349.00 is a reasonable price for Bose QuietComfort Ultra Headphones (2nd Gen).",
  "result": {
    "verdict": "fair",
    "action": "buy_now",
    "confidence": 0.65,
    "evidence": [
      "Same-model Bose QuietComfort Ultra Headphones (2nd Gen) reference: $359.99 for 1 headphone set; your quote is $10.99 lower."
    ]
  }
}
```

Keep null distinct from zero, false and an empty array. Null generally means unknown or unavailable. Optional fields may be omitted. Text summaries can change wording; use documented structured fields when an endpoint provides them.

## Errors and retries

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | Invalid request or tool arguments | Read error_details when present. Correct the field or JSON before retrying. |
| 401 | Missing or invalid authentication | Check the API key and Authorization header; replace a revoked credential. |
| 403 | Access denied | Check account permissions and access. |
| 404 | Unknown tool or path | Check the URL and discover supported names with GET /v1/tools. |
| 405 | Unsupported HTTP method | Use the documented method; tool examples use POST. |
| 429 | Rate limit or exhausted quota | Inspect the error code; these require different handling. |
| 500 / 503 | Service failure or temporary unavailability | Retry only a limited number of times with backoff; contact support if it persists. |

REST tool errors normally include error and error_details. The detail object includes code and message, and may include field, hint or candidate identities. Authentication and gateway failures can have a simpler body; check the HTTP status even when error_details is absent.

HTTP 401 · authentication error (shortened)

```
{
  "error": "unauthorized",
  "error_description": "A credential is required: connect with an MCP client that signs you in (OAuth), or send Authorization: Bearer <API key> (keys: https://app.gaisho.co/console)."
}
```

HTTP 400 · missing required argument

```
{
  "error": "INVALID_ARGUMENT: Missing required argument: offer_ids. Provide the required argument shown in /v1/tools.",
  "error_details": {
    "code": "INVALID_ARGUMENT",
    "message": "Missing required argument: offer_ids.",
    "field": "offer_ids",
    "hint": "Provide the required argument shown in /v1/tools."
  }
}
```

For RATE_LIMITED, wait for the Retry-After interval when supplied and reduce concurrency. For QUOTA_EXCEEDED, check usage and quota in the console; repeated immediate retries do not restore quota.

For MCP tools/call, inspect result.isError and result.structuredContent.error for tool failures, even with HTTP 200. JSON-RPC protocol errors instead use the top-level error object. Authentication can fail before either envelope is created. Client SDKs may expose the inner tool result directly.

MCP tool error · illustrative, shortened

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "INVALID_ARGUMENT",
        "message": "product must be a non-empty string of at most 2000 characters.",
        "field": "product"
      }
    }
  }
}
```

An empty result or unverifiable assessment is not a transport failure. For example, get_offer can return HTTP 200 with a summary saying no offer was found; do not treat it as a usable listing or retry it as a network error.

## Timeouts and application handling

Response time varies with the tool and request. Set a client timeout appropriate to your application and show a loading state. The 60-second timeout in the language examples is an application setting, not a promised response time or an interface-wide execution limit.

An interrupted connection does not establish whether the server finished the request. Avoid immediately starting duplicate calls, and do not retry invalid arguments or unavailable assessments as if they were transient network errors.

Keep API keys out of browser bundles and logs. Record the tool name, HTTP status and a request ID when one is available for troubleshooting. Use the console for current usage and quota rather than hard-coding a plan limit from these examples.

## Endpoint reference

- [Explore a category](https://gaisho.co/docs/api/get_category_overview): Understand a product category, its common specifications, available options and price distribution.
- [Search products](https://gaisho.co/docs/api/search_products): Find products from shopping needs, keywords, a model or a product identifier.
- [Get product details](https://gaisho.co/docs/api/get_product): Read product specifications, ratings, reviews and offers, for one product or up to eight at once.
- [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.
- [Check a seller](https://gaisho.co/docs/api/vet_seller): Assess a seller or online store and return a trust assessment with supporting facts.
- [Search by image](https://gaisho.co/docs/api/search_products_by_image): Identify products in a picture and find matching or similar products in the catalog.