Skip to main content

Getting Started Overview

Welcome to Trading Card API! This guide will help you get up and running quickly, whether you're building your first sports card or trading card application or integrating our API into an existing system.

The same endpoints serve sports card data and trading card data, so a sports card price tracker and a general collection manager start from the same request.

🎯 What You'll Learn​

By the end of this getting started guide, you'll:

  • Have a working API authentication setup
  • Make your first successful API call
  • Understand how to navigate our JSON:API responses
  • Know the common patterns for building card applications

📋 Prerequisites​

To get started with Trading Card API, you'll need:

  • Basic programming knowledge in one of our supported languages (PHP, JavaScript, Python, or cURL)
  • An active internet connection for making API calls
  • A development environment set up for your chosen language

No prior experience with trading cards or card data is required!

🚀 5-Minute Quick Start​

Step 1: Get Your API Key​

Request founding access to get your API key. Founding members get in first while we roll out access.

Step 2: Test Your Connection​

Make a simple API call to verify everything works:

curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Step 3: Explore the Data​

Use our interactive API explorer to browse available endpoints and test requests.

Step 4: Build Your Application​

Follow our guides to build common trading card applications.

🏗️ API Architecture​

Trading Card API is built on modern REST principles with JSON:API specification:

JSON:API Specification​

We follow the JSON:API specification, which provides:

  • Consistent response structure across all endpoints
  • Relationship management between resources
  • Advanced querying with filtering, sorting, and sparse fieldsets
  • Standardized error handling

API Versioning​

Trading Card API uses versioned endpoints (v1 and v2) to ensure stability while improving compliance:

  • v1 endpoints - Original endpoints, stable and fully supported
  • v2 endpoints - Improved JSON:API compliance (currently: /v2/sets/{id}/checklist)
  • Long-term support - Both versions maintained for backward compatibility

When to use:

  • v1 - Existing integrations, backward compatibility needed
  • v2 - New integrations, prefer standards compliance and improved response structures
Version Details

See the API Changelog for complete version history and differences. As of v0.6.0, the v2 checklist endpoint returns cards as primary data (correct JSON:API semantics) vs. v1 which returns the set.

Card Images & Delivery​

Upload, manage, and deliver card images with powerful built-in features:

  • Image upload & management - Store front and back images for your cards
  • Automatic thumbnails - 3 optimized size variants (small, medium, large) generated automatically
  • Global CDN delivery - Fast image loading worldwide via DigitalOcean Spaces
  • Versioned URLs - Automatic cache invalidation when images update
  • CDN redirects - Direct fetching from edge locations for lowest latency

See the Working with Images guide and CDN Integration guide for details.

Core Resources​

Our API is organized around these main resources:

Cards ──┬── Sets
        ├── Players
        ├── Teams
        ├── Card Images
        ├── Attributes
        └── OnCard Relationships

Example Response Structure​

{
  "data": {
    "type": "cards",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "1989 Topps Ken Griffey Jr. #336",
      "number": "336",
      "title": "Rookie Card",
      "serial_number": null
    },
    "relationships": {
      "set": {
        "data": { "type": "sets", "id": "..." }
      }
    }
  },
  "included": [...],
  "meta": { "total": 1247831 }
}

🔐 Authentication Flow​

Trading Card API offers two authentication methods:

Personal Access Tokens (PAT)​

Perfect for development, testing, and personal scripts:

  1. Generate a token from your dashboard
  2. Include it in API requests with Authorization: Bearer YOUR_TOKEN

OAuth 2.0 Client Credentials​

Recommended for production applications:

  1. Register for an account
  2. Create an application to get client credentials
  3. Request an access token using client credentials flow
  4. Include the token in API requests
Pro Tip

Use our authentication guide for detailed setup instructions and code examples for both methods.

📊 Rate Limits & Pricing​

Your rate limit depends on which credential you call with. Anonymous requests get 100 requests/hour and OAuth tokens or Personal Access Tokens get 2,000 requests/hour. A subscriber API key carries your plan's daily allowance instead: 1,000 requests per 24 hours on Starter and 10,000 on Pro, matching the 10,000 you get during the trial. All endpoints are available on every tier, and higher custom limits can be arranged.

🛠️ Development Tools​

SDKs & Libraries​

Testing Tools​

Development Environment​

📖 Next Steps​

Now that you understand the basics, dive deeper:

  1. Set up authentication →
  2. Make your first request →
  3. Explore examples →
  4. Build a card tracker →

💡 Learning Path​

Beginner​

  • Complete authentication setup
  • Make first API call
  • Understand JSON:API responses
  • Explore available endpoints

Intermediate​

  • Implement filtering and sorting
  • Use relationship includes
  • Handle pagination
  • Build error handling

Advanced​

  • Optimize API performance
  • Implement caching strategies
  • Use webhooks for real-time updates
  • Build complex applications

❓ Getting Help​

Stuck? We're here to help:

Ready to dive in? Let's set up your authentication!