Cannons Auctions API

Cannons Auctions API

A REST API integration for Cannons Auctions that provides structured access to auction data including item search, auction listings, and detailed item information.

Overview

The Cannons Auctions API provides programmatic access to auction inventory, enabling:

• Full-text search across auction items
• Browsing current, past, and upcoming auctions
• Retrieving detailed item information including descriptions and images
• Integration with existing applications and workflows

Quick Start

# Install dependencies
npm install

# Start the server
node server.js

# Server runs on http://localhost:1337

MCP (Model Context Protocol)

This API is also available as an MCP server for Claude Code, enabling natural language access to auction data directly from Claude.

Installation

Globally (recommended):

claude mcp add -s user cannons-auctions-mcp node ./mcp/server.js

Per-project:The mcp/ directory and .mcp.json are included in the repo. From the project directory, Claude Code will automatically detect the MCP server.

Available MCP Tools

Usage Example

User: Find all items in the current auction with "chair" in the title
Claude: Uses get_auction_items with search="chair" to return matching items

User: What's the current bid on lot 165?
Claude: Uses search_auctions to find lot 165, returns currentBid

API Endpoints

Health Check

GET /health

Returns server status and timestamp.

Search Auction Items

GET /api/search?search=keyword&filter=Current&sortBy=enddate_asc&page=1&pagesize=100

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "lotNumber": "165",
        "title": "Lot 165",
        "description": null,
        "auctionTitle": "08/04/26: Part 1!! New Kent Online Estate Auction | Aga's Consignments LLC | Providence Forge VA 23140",
        "currentBid": 8,
        "endDate": "2026-08-04T21:16:47.000Z",
        "images": ["https://..."],
        "thumbnail": "https://...",
        "detailUrl": "https://bid.cannonsauctions.com/...",
        "ids": {
          "itemId": "base64-encoded-id",
          "auctionId": "base64-encoded-id",
          "pageNumber": "base64-encoded",
          "pageSize": "base64-encoded"
        }
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalItems": 60,
      "itemsPerPage": 100
    }
  }
}

List Current Auctions

GET /api/auctions?page=1&pagesize=20

Returns auctions grouped by event with item counts and bid ranges.

Response:

{
  "success": true,
  "data": {
    "auctions": [
      {
        "title": "08/04/26: Part 1!! New Kent Online Estate Auction | Aga's Consignments LLC | Providence Forge VA 23140",
        "endDate": "2026-08-04T21:00:00.000Z",
        "itemCount": 100,
        "auctionId": "base64-encoded-id",
        "bidRange": { "min": 31, "max": 210 }
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalItems": 5,
      "itemsPerPage": 20
    }
  }
}

Get Auction Items

GET /api/auctions/:auctionId/items?page=1&pagesize=100

Returns all items for a specific auction.

Response:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "currentPage": 1,
      "totalPages": 10,
      "totalItems": 1000,
      "itemsPerPage": 100
    }
  }
}

Get Item Details

GET /api/item/:itemId/:auctionId?pageNumber=&pageSize=

Retrieves detailed information for a specific auction item.

Response:

{
  "success": true,
  "data": {
    "lotNumber": "100",
    "title": "Plaster 34\" Sculpture of \"Water of Life\" Female Figure",
    "description": "Plaster 34\" Sculpture of \"Water of Life\" Female Figure",
    "category": "Decorative",
    "quantity": 1,
    "startingBid": 13,
    "currentBid": 11,
    "endDate": "2026-08-04T21:00:00.000Z",
    "images": [
      "https://s3.amazonaws.com/prod.maxanet.auction/Can399/Inventory32697260/100_a-3035839a-5a4a-40c5-bad7-cd5117535fb3.jpg"
    ],
    "auctionTitle": ""
  }
}

API Documentation (Swagger)

GET /api-docs

Interactive Swagger UI with all endpoints documented and testable.

Examples

Search for items

curl "http://localhost:1337/api/search?search=plate"

Get all current auctions

curl "http://localhost:1337/api/auctions"

Get item details

curl "http://localhost:1337/api/item/{itemId}/{auctionId}?pageNumber={pageNumber}&pageSize={pageSize}"

Filter by auction status

# Past auctions
curl "http://localhost:1337/api/search?filter=Past&page=1"

# Future auctions
curl "http://localhost:1337/api/search?filter=Future&page=1"

Sort results

# By end date (ascending - ending soonest first)
curl "http://localhost:1337/api/search?sortBy=enddate_asc"

# By end date (descending)
curl "http://localhost:1337/api/search?sortBy=enddate_desc"

# By lot number
curl "http://localhost:1337/api/search?sortBy=ordernumber_asc"

Filter by price range

# Items with bids between $10 and $50
curl "http://localhost:1337/api/search?minBid=10&maxBid=50"

# Items with minimum bid of $100
curl "http://localhost:1337/api/search?minBid=100"

# Items with maximum bid of $25
curl "http://localhost:1337/api/search?maxBid=25"

Architecture

Components

1. Express Server - Handles HTTP requests and routes to appropriate handlers
2. Data Transformation Layer - Transforms Cannons data into consistent JSON structures
3. Session Management - Manages session state for API requests
4. HTML Parser - Uses Cheerio to parse and extract auction data

Key Files

• server.js - Main Express server with all API endpoints
• package.json - Dependencies

Environment

• Node.js 14+ required
• Port: 3000 (configurable via PORT environment variable)

Dependencies

License

This is free and unencumbered software released into the public domain. See UNLICENSE for details.