Introduction
Welcome to the Card Rival API! This RESTful API allows you to integrate Card Rival\'s features into your own applications, enabling programmatic access to packs, cards, battles, and more.
The API is designed to be simple and intuitive, following REST conventions and returning JSON responses.
Authentication
All API requests require authentication using an API key. You can generate your API key from your Card Rival account settings.
API Key Authentication
Include your API key in the Authorization header of every request:
Authorization: Bearer YOUR_API_KEYKeep your API key secure and never share it publicly. If your key is compromised, regenerate it immediately from your account settings.
Base URL
All API endpoints are relative to the following base URL:
https://api.cardrival.com/v1Response Format
All responses are returned in JSON format. Successful responses will have the following structure:
{
"success": true,
"data": {
// Response data here
},
"meta": {
"timestamp": "2025-07-28T10:30:00Z",
"request_id": "req_abc123"
}
}Error Handling
When an error occurs, the API will return an appropriate HTTP status code along with an error response:
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "The request was invalid",
"details": "Pack ID not found"
}
}Common Error Codes
Packs
Endpoints for listing, purchasing, and opening mystery packs.
Retrieve a list of all available packs.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| category | string | Filter by category (baseball, basketball, football) |
| sort | string | Sort by: price_asc, price_desc, newest, popular |
| limit | integer | Number of results per page (default: 20, max: 100) |
Response Example
{
"success": true,
"data": {
"packs": [
{
"id": "pack_123",
"name": "Premium Baseball Mystery Pack",
"description": "Contains 5 random baseball cards",
"price": 24.99,
"category": "baseball",
"available": 150,
"odds": {
"common": 0.60,
"rare": 0.30,
"epic": 0.08,
"legendary": 0.02
}
}
],
"total": 42,
"page": 1
}
}Purchase a mystery pack.
Request Body
| Parameter | Type | Description |
|---|---|---|
| quantity | integer | Number of packs to purchase Required |
| payment_method | string | Payment method ID |
Open a purchased pack to reveal cards.
Response Example
{
"success": true,
"data": {
"cards": [
{
"id": "card_456",
"vault_id": "VLT-2025-456",
"name": "Mike Trout",
"year": 2023,
"set": "Topps Chrome",
"rarity": "rare",
"condition": "mint",
"image_url": "https://cdn.cardrival.com/cards/456.jpg"
}
]
}
}Cards
Endpoints for managing individual cards.
Get detailed information about a specific card.
Response Example
{
"success": true,
"data": {
"card": {
"id": "card_456",
"vault_id": "VLT-2025-456",
"name": "Mike Trout",
"year": 2023,
"set": "Topps Chrome",
"card_number": "MT-01",
"rarity": "rare",
"condition": "mint",
"cr_score": 9.2,
"market_value": 125.00,
"population": 500,
"attributes": {
"autographed": false,
"parallel": "refractor",
"serial_numbered": false
}
}
}
}Rate Limits
API rate limits vary by plan tier. Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1627849200| Plan | Requests/Minute | Burst Limit |
|---|---|---|
| Free | 60 | 10 |
| Standard | 100 | 20 |
| Pro | 500 | 50 |
| Enterprise | Custom | Custom |