Card Batch API

Card Batch converts structured card identity fields into precise eBay searches and processes them as a background job. Each completed card consumes one normal monthly request.

Submit a batch

curl -X POST "https://api.compsniper.com/v1/cards/batch" \
  -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inventory-run-2026-08-31" \
  -d '{
    "cards": [
      {
        "reference": "inventory-001",
        "year": 2023,
        "set": "Topps Chrome",
        "player": "Victor Wembanyama",
        "cardNumber": "1",
        "parallel": "Refractor",
        "grader": "PSA",
        "grade": 10
      },
      {
        "reference": "inventory-002",
        "keyword": "1999 pokemon base set charizard 4/102 psa 9"
      }
    ],
    "options": {
      "count": 60,
      "outputMode": "summary",
      "relevance": true
    }
  }'

An explicit keyword overrides generated card fields. Otherwise, combine year, set, subject, player, character, cardNumber, parallel, grader, and grade.

Poll or cancel

curl -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  "https://api.compsniper.com/v1/cards/batch/JOB_ID"

• GET /v1/cards/batch/:jobId returns progress and completed card results.
• DELETE /v1/cards/batch/:jobId stops unfinished work safely.
• Results remain available for 30 days.
• Reuse an Idempotency-Key when retrying submission after a network failure.

Output modes

• summary: up to 100 cards with cleaned price summaries.
• compact: up to 25 cards and 60 sold rows per card.

Compact rows include bestOfferAccepted. When it is true, eBay marked an accepted Best Offer but did not reveal the actual accepted amount. Exclude those rows when exact transaction price is required.