Grabblist

Test connectivity to Grabblist and return service version.

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

Get all saved items from the user's Grabblist. Each item is a static snapshot — data reflects the moment it was saved, not current prices.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "description": "Max items to return (default: 50)"
    },
    "platform": {
      "type": "string",
      "description": "Filter by platform (domain name, e.g. \"amazon\", \"ebay\", \"trademe\")"
    }
  }
}

Get full details of a saved item by ID. Returns a static snapshot from the user's Grabblist.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The item ID"
    }
  },
  "required": [
    "id"
  ]
}

Save an item to the user's Grabblist. Creates a static snapshot — Grabblist does not monitor prices or auto-update data. Only include fields with values available from the source. If no image is provided, the server attempts to fetch og:image automatically.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "object",
      "description": "Direct public HTTP(S) page URL."
    },
    "title": {
      "type": "string",
      "maxLength": 500,
      "description": "Exact title from the page"
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "Price as number (e.g. 99.99) — REQUIRED, extract from page"
    },
    "currency": {
      "type": "string",
      "maxLength": 10,
      "description": "Currency code: USD, NZD, AUD, EUR, GBP, etc."
    },
    "image": {
      "type": "object",
      "description": "Main image URL. Server auto-fetches og:image if not provided."
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "All image URLs found on the page"
    },
    "platform": {
      "type": "string",
      "maxLength": 100,
      "description": "Site domain name without TLD: amazon.com→\"amazon\", ebay.co.nz→\"ebay\", kiwiquads.co.nz→\"kiwiquads\""
    },
    "item_type": {
      "type": "string",
      "enum": [
        "product",
        "rental",
        "service",
        "course",
        "listing",
        "event",
        "other"
      ],
      "description": "What kind of item: product (buy), rental (Airbnb), service (cleaning), course (Udemy), listing (classified), event (ticket). Default: product."
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "Description from the page (max 2000 chars)"
    },
    "condition": {
      "type": "string",
      "maxLength": 100,
      "description": "Condition if applicable: New, Used, Refurbished, Used - Like New, Used - Good, Used - Fair"
    },
    "location": {
      "type": "string",
      "maxLength": 500,
      "description": "Seller location or pickup location"
    },
    "category": {
      "type": "string",
      "enum": [
        "electronics",
        "furniture",
        "home",
        "clothing",
        "vehicles",
        "kids",
        "sports",
        "collectibles",
        "tools",
        "other"
      ],
      "description": "Category — pick the best match"
    },
    "seller_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Seller or store name"
    },
    "seller_rating": {
      "type": "number",
      "minimum": 0,
      "maximum": 5,
      "description": "Seller rating 0-5"
    },
    "seller_reviews": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000,
      "description": "Number of seller reviews"
    },
    "original_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "Original price before discount (if on sale)"
    },
    "attributes": {
      "type": "object",
      "description": "Specs/details as key-value pairs"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      },
      "description": "Tags for categorization"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000,
      "description": "How many of this item"
    },
    "posted_at": {
      "type": "string",
      "maxLength": 64,
      "description": "When the listing was originally posted (ISO 8601)"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000,
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "url",
    "title",
    "price",
    "currency",
    "platform"
  ]
}

Remove one or more items from the user's Grabblist (soft-delete). Pass a single id or an array of ids for batch operations.

{
  "type": "object",
  "properties": {
    "id": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Item ID or array of item IDs to delete"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000,
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id"
  ]
}

Restore one or more deleted (archived) items back to the Grabblist. Pass a single id or an array of ids for batch restore.

{
  "type": "object",
  "properties": {
    "id": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Item ID or array of item IDs to restore"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000,
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id"
  ]
}

Search within the user's saved items by keyword

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 500,
      "description": "Search query"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 50,
      "description": "Max results (default: 20)"
    }
  },
  "required": [
    "query"
  ]
}

Manually update the price on a saved item. Records old and new price for comparison. This is a manual correction, not automatic price tracking.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The item ID"
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "New current price"
    },
    "source": {
      "type": "string",
      "enum": [
        "ai_check",
        "manual"
      ],
      "description": "Price update source"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id",
    "price"
  ]
}

Edit fields on one or more saved items. Pass a single id or an array of ids for batch updates (same fields applied to all). For batch: attributes are REPLACED not merged, og:image fallback is skipped.

{
  "type": "object",
  "properties": {
    "id": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Item ID or array of item IDs to update"
    },
    "notes": {
      "type": "string",
      "maxLength": 2000,
      "description": "User or AI notes — personal comments, thoughts, comparisons"
    },
    "status": {
      "type": "string",
      "enum": [
        "considering",
        "shortlisted",
        "decided",
        "bought",
        "rejected"
      ],
      "description": "Decision status: considering, shortlisted, decided, bought, rejected"
    },
    "item_type": {
      "type": "string",
      "enum": [
        "product",
        "rental",
        "service",
        "course",
        "listing",
        "event",
        "other"
      ],
      "description": "What kind of item this is"
    },
    "category": {
      "type": "string",
      "enum": [
        "electronics",
        "furniture",
        "home",
        "clothing",
        "vehicles",
        "kids",
        "sports",
        "collectibles",
        "tools",
        "other"
      ],
      "description": "Item category"
    },
    "target_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "What the user wants to pay — not the actual price, but the goal price"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      },
      "description": "Replace all tags with this list"
    },
    "attributes": {
      "type": "object",
      "description": "Merge into existing attributes"
    },
    "image_url": {
      "type": "object",
      "description": "Main image URL"
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "All image URLs — replaces the entire images array"
    },
    "title": {
      "type": "string",
      "maxLength": 500,
      "description": "Item title"
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "Item description (max 2000 chars)"
    },
    "is_favorite": {
      "type": "boolean",
      "description": "Set true to favorite, false to unfavorite"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000,
      "description": "How many of this item"
    },
    "reason": {
      "type": "string",
      "maxLength": 1000,
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id"
  ]
}

List all collections OR get a specific collection with its items. Without id: returns all collections with counts/values. With id: returns that collection's metadata and all items inside (with optional filters).

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Collection ID — if provided, returns that collection with all its items. If omitted, lists all collections."
    },
    "status": {
      "type": "string",
      "enum": [
        "considering",
        "shortlisted",
        "decided",
        "bought",
        "rejected"
      ],
      "description": "Filter by decision status (only when id is provided)"
    },
    "created_by": {
      "type": "string",
      "enum": [
        "user",
        "ai",
        "extension"
      ],
      "description": "Filter by who added: \"ai\" for AI-added items (only when id is provided)"
    },
    "min_price": {
      "type": "number",
      "description": "Minimum price filter (only when id is provided)"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price filter (only when id is provided)"
    },
    "platform": {
      "type": "string",
      "description": "Filter by platform domain name, e.g. \"amazon\", \"ebay\" (only when id is provided)"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter items that have ALL these tags (only when id is provided)"
    },
    "sort": {
      "type": "string",
      "enum": [
        "newest",
        "oldest",
        "price_asc",
        "price_desc",
        "title"
      ],
      "description": "Sort order (only when id is provided, default: newest)"
    }
  }
}

Create a new collection (folder) in the user's Grabblist to organize saved items.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Collection name, e.g. \"Gaming Setup\" or \"Gift Ideas\""
    },
    "icon": {
      "type": "string",
      "description": "Material Symbols icon name (e.g. \"devices\", \"home\", \"shopping_bag\", \"checkroom\", \"directions_car\", \"favorite\"). Default: inventory_2"
    },
    "color": {
      "type": "string",
      "description": "Hex color for the collection (e.g. \"#3B82F6\", \"#22C55E\", \"#A855F7\", \"#EC4899\", \"#F59E0B\", \"#EF4444\"). Default: #3B82F6"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Short description of what this collection is for"
    },
    "budget": {
      "type": "number",
      "description": "Total spending target for this collection (e.g. 1500 for \"Build PC under $1500\")"
    },
    "budget_currency": {
      "type": "string",
      "description": "Currency for the budget (default: NZD)"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "name"
  ]
}

Add a saved item to a collection. Both the item and collection must already exist.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "description": "The collection ID"
    },
    "item_id": {
      "type": "string",
      "description": "The item ID to add"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "collection_id",
    "item_id"
  ]
}

Remove one or more items from a collection. Pass a single item_id or an array of item_ids for batch removal. Items are NOT deleted — they stay in the Grabblist.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "description": "The collection ID"
    },
    "item_ids": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Item ID or array of item IDs to remove"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "collection_id",
    "item_ids"
  ]
}

Permanently delete a collection. Items inside are not deleted — they stay in the Grabblist.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The collection ID to delete"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id"
  ]
}

Update a collection's name, icon, description, budget, or sharing status. Only provide the fields you want to change — omitted fields stay unchanged. Set is_public=true to share (returns public URL), is_public=false to unshare.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The collection ID to update"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "New collection name"
    },
    "icon": {
      "type": "string",
      "description": "Material Symbols icon name (e.g. \"devices\", \"home\", \"shopping_bag\")"
    },
    "color": {
      "type": "string",
      "description": "Hex color (e.g. \"#3B82F6\", \"#22C55E\", \"#EF4444\")"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "New description"
    },
    "budget": {
      "type": "number",
      "description": "New budget amount"
    },
    "budget_currency": {
      "type": "string",
      "description": "New budget currency"
    },
    "is_public": {
      "type": "boolean",
      "description": "Set true to share (generates public URL), false to unshare"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "id"
  ]
}

Create typed relations between items: alternative (A or B), complement (A and B together), upgrade (B replaces A), duplicate (same item different site), same_seller. Supports single pair (from_id, to_id, relation) or bulk (pairs array).

{
  "type": "object",
  "properties": {
    "from_id": {
      "type": "string",
      "description": "First item ID (for single pair mode)"
    },
    "to_id": {
      "type": "string",
      "description": "Second item ID (for single pair mode)"
    },
    "relation": {
      "type": "string",
      "enum": [
        "alternative",
        "complement",
        "upgrade",
        "duplicate",
        "same_seller"
      ],
      "description": "Type of relationship (for single pair mode)"
    },
    "pairs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from_id": {
            "type": "string",
            "description": "First item ID"
          },
          "to_id": {
            "type": "string",
            "description": "Second item ID"
          },
          "relation": {
            "type": "string",
            "enum": [
              "alternative",
              "complement",
              "upgrade",
              "duplicate",
              "same_seller"
            ],
            "description": "Type of relationship"
          }
        },
        "required": [
          "from_id",
          "to_id",
          "relation"
        ]
      },
      "description": "Array of pairs to link (for bulk mode)"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  }
}

Get all relations for an item — alternatives, complements, upgrades, duplicates. Returns the item and all connected items with their relation types.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The item ID to get relations for"
    }
  },
  "required": [
    "id"
  ]
}

Remove a relation between two items.

{
  "type": "object",
  "properties": {
    "from_id": {
      "type": "string",
      "description": "First item ID"
    },
    "to_id": {
      "type": "string",
      "description": "Second item ID"
    },
    "relation": {
      "type": "string",
      "enum": [
        "alternative",
        "complement",
        "upgrade",
        "duplicate",
        "same_seller"
      ],
      "description": "The relation type to remove"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "from_id",
    "to_id",
    "relation"
  ]
}

Get the change history for a saved item — who changed what and when.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "description": "The item ID"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 50,
      "description": "Max events to return (default: 20)"
    }
  },
  "required": [
    "item_id"
  ]
}

Get recent activity on a collection — additions, removals, edits.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "description": "The collection ID"
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 50,
      "description": "Max events to return (default: 20)"
    }
  },
  "required": [
    "collection_id"
  ]
}

Set the pinned "Top Picks" items for a collection (max 3). Pinned items are highlighted on the share page.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "description": "The collection ID"
    },
    "item_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Items to pin, in display order (1st = top)"
    },
    "reason": {
      "type": "string",
      "description": "Why this change was made (shown to user in change history)"
    }
  },
  "required": [
    "collection_id",
    "item_ids"
  ]
}

Send feedback, bug report, or feature request to the Grabbit team. Use this when you encounter parsing failures, missing features, broken URLs, or have improvement suggestions. The team reads these to improve the product. Be specific about what went wrong and where.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "bug",
        "parsing_failure",
        "feature_request",
        "feedback"
      ],
      "description": "Type: bug (something broken), parsing_failure (price/title/image not extracted), feature_request (wishlist), feedback (general feedback)"
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "What happened or what you propose. Be specific — the team reads this."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The URL where the issue occurred"
    },
    "tool": {
      "type": "string",
      "description": "The tool you were using when the issue occurred (e.g. add_item, search_saved)"
    },
    "error": {
      "type": "string",
      "description": "Error message you received, if any"
    }
  },
  "required": [
    "type",
    "message"
  ]
}

Delegate a task to Grabblist's built-in AI assistant. The agent knows the user's Grabblist and can answer questions, compare items, give shopping advice, or analyze saved products. Use this when you want a second opinion or a specialized shopping assistant perspective. Requires the user to have an Anthropic API key configured in Settings.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "maxLength": 4000,
      "description": "The question or task for the Grabblist assistant"
    },
    "model": {
      "type": "string",
      "enum": [
        "haiku",
        "sonnet",
        "opus"
      ],
      "description": "AI model to use (default: sonnet). haiku=fast/cheap, sonnet=balanced, opus=most capable"
    }
  },
  "required": [
    "message"
  ]
}