cURL Examples

Authentication

Using Personal Access Token (Recommended for Development)

# Set your token as an environment variable
export TRADING_CARD_API_PAT="your_personal_access_token"

# Use it in requests
curl -X GET "https://api.tradingcardapi.com/v1/cards?page[limit]=5" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

Using OAuth 2.0 Client Credentials (Recommended for Production)

# Step 1: Get access token
TOKEN_RESPONSE=$(curl -X POST "https://api.tradingcardapi.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }')

# Step 2: Extract token
ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')

# Step 3: Use token in requests
curl -X GET "https://api.tradingcardapi.com/v1/cards?page[limit]=5" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

Basic Usage

# List cards with pagination
curl -X GET "https://api.tradingcardapi.com/v1/cards?page[limit]=25&page[offset]=0" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Get a specific card
curl -X GET "https://api.tradingcardapi.com/v1/cards/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

Advanced Filtering

# Search with multiple filters
curl -X GET "https://api.tradingcardapi.com/v1/cards?filter[year]=1989&filter[name]=*Griffey*&include=set,oncard&sort=name&page[limit]=50" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Filter by set
curl -X GET "https://api.tradingcardapi.com/v1/cards?filter[set.name]=Topps&filter[year]=2023" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

Cards

Fetch Card with Image Reference

# Get a card and check for image_uuid (v0.6.0+)
curl -X GET "https://api.tradingcardapi.com/v1/cards/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Response includes image_uuid if an image has been uploaded
# {
#   "data": {
#     "type": "cards",
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "attributes": {
#       "name": "Ken Griffey Jr.",
#       "number": "1",
#       "image_uuid": "01234567-89ab-cdef-0123-456789abcdef"
#     }
#   }
# }

Include Card Images in Response

# Fetch card with related images included (v0.7.0+)
curl -X GET "https://api.tradingcardapi.com/v1/cards/550e8400-e29b-41d4-a716-446655440000?include=images" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Response includes card data and related images in 'included' array
# {
#   "data": {
#     "type": "cards",
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "attributes": { ... },
#     "relationships": {
#       "images": {
#         "data": [
#           { "type": "card_images", "id": "01234567-89ab-cdef-0123-456789abcdef" }
#         ]
#       }
#     }
#   },
#   "included": [
#     {
#       "type": "card_images",
#       "id": "01234567-89ab-cdef-0123-456789abcdef",
#       "attributes": {
#         "side": "front",
#         "image_url": "https://cdn.tradingcardapi.com/images/...",
#         "variants": { ... }
#       }
#     }
#   ]
# }

List Cards with Images

# List cards and include their images
curl -X GET "https://api.tradingcardapi.com/v1/cards?filter[set_id]=550e8400-e29b-41d4-a716-446655440000&include=images,set&page[limit]=25" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Response includes cards with image_uuid and related CardImage resources in 'included' array
# Check each card's attributes.image_uuid to see if it has an image
# Access full image details from the 'included' array by matching the relationship ID

File Uploads

Upload Card Image

# Upload a card image with multipart/form-data
curl -X POST "https://api.tradingcardapi.com/v1/card-images" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -F "file=@/path/to/card-front.jpg" \
  -F 'data={"type":"card_images","attributes":{"card_id":"550e8400-e29b-41d4-a716-446655440000","image_type":"front"}}'

# Response includes the image ID and CDN URLs
# {
#   "data": {
#     "type": "card_images",
#     "id": "01234567-89ab-cdef-0123-456789abcdef",
#     "attributes": {
#       "variants": {
#         "small": { "url": "https://cdn.tradingcardapi.com/images/...?v=1234567890", "width": 150 },
#         "medium": { "url": "https://cdn.tradingcardapi.com/images/...?v=1234567890", "width": 300 },
#         "large": { "url": "https://cdn.tradingcardapi.com/images/...?v=1234567890", "width": 600 }
#       }
#     }
#   }
# }

Download Card Image

# Download specific size variant
curl -X GET "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef/download?size=medium" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o card-image.jpg

# Download original image
curl -X GET "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef/download" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o card-original.jpg

# Follow CDN redirect (API returns 302 to CDN)
curl -L -X GET "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef/download?size=large" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o card-large.jpg

Update Card Image Metadata

# Update image metadata (e.g., change image type)
curl -X PATCH "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "card_images",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "image_type": "back"
      }
    }
  }'

Delete Card Image

# Delete a card image
curl -X DELETE "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Successful deletion returns 204 No Content

List Card Images

# List all images for a specific card
curl -X GET "https://api.tradingcardapi.com/v1/card-images?filter[card_id]=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

Responsive Images with Versioned CDN URLs

Fetch Image Metadata

# Get image metadata with all size variants
IMAGE_RESPONSE=$(curl -X GET "https://api.tradingcardapi.com/v1/card-images/01234567-89ab-cdef-0123-456789abcdef" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json")

# Extract variant URLs (using jq for JSON parsing)
SMALL_URL=$(echo $IMAGE_RESPONSE | jq -r '.data.attributes.variants.small.url')
MEDIUM_URL=$(echo $IMAGE_RESPONSE | jq -r '.data.attributes.variants.medium.url')
LARGE_URL=$(echo $IMAGE_RESPONSE | jq -r '.data.attributes.variants.large.url')

# URLs include version parameter for cache invalidation
# Example: https://cdn.tradingcardapi.com/images/abc123.jpg?v=1699564800

Generate Responsive HTML

# Generate responsive image HTML
cat << EOF
<img
  src="$SMALL_URL"
  srcset="
    $SMALL_URL 150w,
    $MEDIUM_URL 300w,
    $LARGE_URL 600w
  "
  sizes="(max-width: 640px) 150px, 300px"
  alt="Card image"
  loading="lazy"
/>
EOF

Batch Download Multiple Sizes

# Download all size variants for a card image
IMAGE_ID="01234567-89ab-cdef-0123-456789abcdef"

curl -X GET "https://api.tradingcardapi.com/v1/card-images/$IMAGE_ID/download?size=small" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o "card-small.jpg"

curl -X GET "https://api.tradingcardapi.com/v1/card-images/$IMAGE_ID/download?size=medium" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o "card-medium.jpg"

curl -X GET "https://api.tradingcardapi.com/v1/card-images/$IMAGE_ID/download?size=large" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -o "card-large.jpg"

echo "Downloaded all variants successfully"

Error Handling

# Upload with error handling
HTTP_CODE=$(curl -X POST "https://api.tradingcardapi.com/v1/card-images" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -F "file=@/path/to/card.jpg" \
  -F 'data={"type":"card_images","attributes":{"card_id":"550e8400-e29b-41d4-a716-446655440000","image_type":"front"}}' \
  -w "%{http_code}" \
  -o response.json)

if [ "$HTTP_CODE" -eq 201 ]; then
  echo "Image uploaded successfully"
  cat response.json | jq '.'
else
  echo "Upload failed with status $HTTP_CODE"
  cat response.json | jq '.errors'
fi

Set Sources

Create Set Source

# Add a checklist source to a set
curl -X POST "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "set_sources",
      "attributes": {
        "set_id": "550e8400-e29b-41d4-a716-446655440000",
        "source_type": "checklist",
        "source_name": "Beckett Online Price Guide",
        "source_url": "https://www.beckett.com/price-guides"
      }
    }
  }'

# Response includes source ID and details
# {
#   "data": {
#     "type": "set_sources",
#     "id": "01234567-89ab-cdef-0123-456789abcdef",
#     "attributes": {
#       "set_id": "550e8400-e29b-41d4-a716-446655440000",
#       "source_type": "checklist",
#       "source_name": "Beckett Online Price Guide",
#       "source_url": "https://www.beckett.com/price-guides",
#       "verified_at": null
#     }
#   }
# }

List Sources for a Set

# Get all sources for a specific set
SET_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://api.tradingcardapi.com/v1/set-sources?filter[set_id]=$SET_ID" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Parse and display sources with jq
curl -X GET "https://api.tradingcardapi.com/v1/set-sources?filter[set_id]=$SET_ID" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json" | jq '.data[] | {
    type: .attributes.source_type,
    name: .attributes.source_name,
    url: .attributes.source_url,
    verified: .attributes.verified_at
  }'

Get Set with Sources Included

# Fetch a set with all its sources using include parameter
SET_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://api.tradingcardapi.com/v1/sets/$SET_ID?include=sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Display set name and all sources
curl -X GET "https://api.tradingcardapi.com/v1/sets/$SET_ID?include=sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json" | jq '{
    set: .data.attributes.name,
    year: .data.attributes.year,
    sources: [.included[]? | select(.type == "set_sources") | {
      type: .attributes.source_type,
      name: .attributes.source_name
    }]
  }'

Update Source Verification

# Update a source to mark it as verified
SOURCE_ID="01234567-89ab-cdef-0123-456789abcdef"
VERIFIED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

curl -X PATCH "https://api.tradingcardapi.com/v1/set-sources/$SOURCE_ID" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
    "data": {
      "type": "set_sources",
      "id": "$SOURCE_ID",
      "attributes": {
        "verified_at": "$VERIFIED_AT"
      }
    }
  }"

# Display verification timestamp
echo "Source verified at: $VERIFIED_AT"

Delete Set Source

# Remove a source from a set
SOURCE_ID="01234567-89ab-cdef-0123-456789abcdef"

curl -X DELETE "https://api.tradingcardapi.com/v1/set-sources/$SOURCE_ID" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# Successful deletion returns 204 No Content

Track Multiple Source Types

# Add multiple sources for different data types
SET_ID="550e8400-e29b-41d4-a716-446655440000"

# Add checklist source
curl -X POST "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
    "data": {
      "type": "set_sources",
      "attributes": {
        "set_id": "$SET_ID",
        "source_type": "checklist",
        "source_name": "COMC Database",
        "source_url": "https://www.comc.com"
      }
    }
  }"

# Add metadata source
curl -X POST "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
    "data": {
      "type": "set_sources",
      "attributes": {
        "set_id": "$SET_ID",
        "source_type": "metadata",
        "source_name": "CardboardConnection",
        "source_url": "https://www.cardboardconnection.com"
      }
    }
  }"

# Add images source
curl -X POST "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
    "data": {
      "type": "set_sources",
      "attributes": {
        "set_id": "$SET_ID",
        "source_type": "images",
        "source_name": "Trading Card Database",
        "source_url": "https://www.tradingcarddb.com"
      }
    }
  }"

echo "Added 3 sources (checklist, metadata, images)"

v2 Endpoints

Get Set Checklist (v2)

# v2 endpoint returns cards as primary data (correct JSON:API semantics)
SET_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://api.tradingcardapi.com/v2/sets/$SET_ID/checklist" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

Compact Format for Large Sets

# Use compact format to reduce response size by ~75%
SET_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://api.tradingcardapi.com/v2/sets/$SET_ID/checklist?format=compact" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

v1 vs v2 Comparison

SET_ID="550e8400-e29b-41d4-a716-446655440000"

# v1 endpoint (set as primary data)
curl -X GET "https://api.tradingcardapi.com/v1/sets/$SET_ID/checklist" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"

# v2 endpoint (cards as primary data - preferred for new integrations)
curl -X GET "https://api.tradingcardapi.com/v2/sets/$SET_ID/checklist" \
  -H "Authorization: Bearer $TRADING_CARD_API_PAT" \
  -H "Accept: application/vnd.api+json"