Agent skill

A single, copy-pasteable spec that teaches a coding agent every Grail endpoint, parameter, and response field — so it writes correct calls the first time.

What it is

Point your coding agent (Claude Code, Codex, Cursor, Windsurf, or a custom one) at the skill below and it stops guessing the API. It covers the endpoint, the filters, the honest response shape, and the rules an agent most often gets wrong — string prices, pagination, and 429 backoff.

The skill

Save this as a file your agent reads (e.g. AGENTS.md or a skill doc), or paste it into the system prompt.

# Grail API — agent skill

Base URL:  https://grail.solutions
Auth:      Authorization: Bearer gk_live_<key>
Endpoint:  GET /v1/scrape

## Search sold comps
GET /v1/scrape?keyword=<text>&count=<1-240>&sold=true&page=<n>

Optional filters:
  condition=new|used|<eBay condition id>
  minPrice / maxPrice        (numbers)
  days                       (1-90, sold window)
  ebaySite                   (ebay.com, ebay.co.uk, ... 8 sites)
  relevance=false            (raw eBay feed; default = AI-cleaned)

## Response shape
{ keyword, page, totalItems, hasNextPage,
  rawMedian, rawSampleCount,
  summary: { count, currency, median, mean, min, max, p25, p75, avgShipping },
  items: [{ itemId, title, url, condition, conditionId,
            soldPrice, shippingPrice, totalPrice, endedAt, ... }] }

## Rules
- Prices are decimal STRINGS; parse before math.
- Check hasNextPage before paginating; count caps at 240.
- On 429, back off (see /docs/rate-limits); do not hot-loop.
- Use relevance=false only when you truly want the raw feed.

## Shipping
GET /api/shipping-rates?weight=<lb>&to=<zip>   (same key)

Download

Grab the skill as a file and drop it into your repo:

Download grail-agent-skill.mdcurl -O https://grail.solutions/grail-agent-skill.md

Prefer a live connection?

If your client speaks MCP, connect it instead so the agent can call Grail directly — see the MCP connector.