Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Hobby Card Index Data Usage API
version: '1'
summary: Real sold prices, photo identification, cert lookups, pop reports, sold sales and price history for sports cards and trading cards.
description: 'Real sold prices for sports cards and trading cards: a catalog of more than 16 million cards across 25-plus categories (baseball, basketball, football, hockey, soccer, Pokemon, Magic: The Gathering, Yu-Gi-Oh, One Piece and more) with more than 22 million raw and graded prices, refreshed daily, plus card identification from a photo, PSA, BGS, CGC and SGC cert lookups, population reports, verified sold-sale records, daily price history, set lists, market movers, a price watch list with a daily webhook, and bulk price files.
## Keys and plans
Every endpoint needs an API key, sent as the `X-API-Key` header (or `Authorization: Bearer`). Keys come from Settings, API Access, after subscribing. An **Enterprise** plan ($49.99 a month) includes a key for your own business''s internal use: 1 request a second, up to 100,000 a day. Apps, websites and products whose users see the data need a **Commercial plan** (a commercial data license, Terms of Service section 8):
- Lite (plan id `lite`): $99 a month; 25,000 requests, 25,000 photo scans, 5,000 sold-sale lookups, 150 cert lookups, 10 lookups a second, price history.
- Growth Lite (plan id `growth_lite`): $249 a month; 125,000 requests, 125,000 photo scans, 25,000 sold-sale lookups, 750 cert lookups, 15 lookups a second, price history.
- Growth (plan id `growth`): $499 a month; 500,000 requests, 500,000 photo scans, 100,000 sold-sale lookups, 3,000 cert lookups, 20 lookups a second, price history.
- Platform (plan id `platform`): from $1,500 a month; 2,000,000 requests, 1,500,000 photo scans, 500,000 sold-sale lookups, 50,000 cert lookups, 50 lookups a second, price history, bulk price files.
A **free setup month** is by application in Settings, API Access (one per company): enough to build and test against real data, with daily pools. Plans, prices and how to buy, including how an AI agent can buy a plan for its user with no account (GET /api/v1/agent/plans, POST /api/v1/agent/checkout): https://hobbycardindex.com/developers#commercial-plans. Questions or a bigger deal: sean@hobbycardindex.com.
## Credit the data (required)
Commercial plans ask for one link back to https://hobbycardindex.com somewhere on your site, such as ''Prices and API supplied by Hobby Card Index''; it does not need to be beside the prices. Every successful JSON object response carries an `attribution` object (text, url, html, required, terms) and an `X-Attribution` header with the same credit, so it can be rendered straight from the response. Put the credit beside the prices or anywhere on your website, such as the footer. Snippet: `Prices from Hobby Card Index`.
## Conventions
- Base URL `https://hobbycardindex.com`; every path starts with `/api/v1/`. Prices are US dollars with two decimals; a grade with no price is `null`. Grade keys: `loose` (raw), `psa10`, `psa9`, `psa8`, `psa7`, `bgs10` (BGS 9.5), `cgc10`, `sgc10`.
- Successful responses are `{ "success": true, "data": { ... }, "attribution": { ... } }`; errors are `{ "success": false, "error": { "code", "message", "details"? } }` with the HTTP status that fits (400, 401, 402, 403, 404, 409, 413, 429, 500, 503). Streamed downloads (CSV, bulk files, the watch-list prices) are not wrapped.
- Card ids: pass the integer `id` every response carries, or `ext-` plus the card''s `externalId`. Picture links (`imageUrl`) go through our image proxy and need no key; a link can answer 404 later if the picture is withdrawn, so show a placeholder on a 404.
- Rate limits: 1 request a second on an Enterprise key, the plan''s lookups a second on a commercial key, with `RateLimit-*` and `X-RateLimit-*` headers on the one-second window. Commercial plans also return `X-HCI-Plan` and `X-HCI-*-Used` / `X-HCI-*-Allowance` headers for the monthly counters.
- The same data through an MCP server for AI assistants: POST https://hobbycardindex.com/api/v1/mcp, manifest https://hobbycardindex.com/.well-known/mcp.json.'
termsOfService: https://hobbycardindex.com/terms/
contact:
name: Sean Charman, Hobby Card Index
email: sean@hobbycardindex.com
url: https://hobbycardindex.com/developers
license:
name: Hobby Card Index Terms of Service (section 8, Commercial Data License)
url: https://hobbycardindex.com/terms/#data-license
x-logo:
url: https://hobbycardindex.com/hci-logo2.png
altText: Hobby Card Index
href: https://hobbycardindex.com
x-attribution:
text: Prices from Hobby Card Index
url: https://hobbycardindex.com
html: <a href="https://hobbycardindex.com" rel="noopener">Prices from Hobby Card Index</a>
required: true
terms: https://hobbycardindex.com/terms/
servers:
- url: https://hobbycardindex.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Usage
description: The key's plan, limits and usage.
paths:
/api/v1/usage:
get:
tags:
- Usage
summary: This key's plan, limits and month-to-date usage
operationId: getUsage
description: 'What the key can do and how much of it is used. Commercial plans see their monthly allowances (requests, scans, sold-sale, cert and pop lookups), per-second limits, overage terms and, on a free setup month, when it ends. An Enterprise key sees the self-serve model: 1 request a second.'
responses:
'200':
description: Usage for the key
headers:
X-Attribution:
$ref: '#/components/headers/X-Attribution'
X-HCI-Plan:
$ref: '#/components/headers/X-HCI-Plan'
X-HCI-Requests-Used:
$ref: '#/components/headers/X-HCI-Requests-Used'
X-HCI-Requests-Allowance:
$ref: '#/components/headers/X-HCI-Requests-Allowance'
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
const: true
data:
$ref: '#/components/schemas/Usage'
attribution:
$ref: '#/components/schemas/Attribution'
required:
- success
- data
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServerError'
security:
- ApiKeyAuth: []
components:
responses:
TooManyRequests:
description: RATE_LIMITED (the per-second window; slow down and retry), RATE_LIMIT_EXCEEDED (the daily ceiling), MONTHLY_LIMIT_REACHED, DAILY_LIMIT_REACHED, SALES_LIMIT_REACHED, CERT_LIMIT_REACHED, POP_LIMIT_REACHED, LISTINGS_LIMIT_REACHED, SCAN_ENGINE_BUSY (Retry-After says when).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: 'SERVER_ERROR (500 or 503): something failed on our side; retry in a minute.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentRequired:
description: 'TRIAL_ENDED: the free setup month is over and the first month of the plan is not paid yet.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: 'The request is not valid: VALIDATION_ERROR, INVALID_PARAM, BAD_REQUEST, SEARCH_TOO_BROAD, NO_IMAGE, INVALID_IMAGE.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: 'The key''s plan does not include this: PLAN_REQUIRED, DEALER_KEY_SCOPE, NOT_ON_PLAN, REQUIRES_COMMERCIAL_LICENSE, REQUIRES_GROWTH, REQUIRES_PARTNER_PLAN, REQUIRES_PLATFORM_PLAN, REQUIRES_PRICE_FILES, REQUIRES_ENTERPRISE, LISTINGS_NOT_ENABLED. The message says which plan has it and `details.plans_url` where to get it.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: No key (MISSING_API_KEY), a key we do not know (INVALID_API_KEY) or one that was revoked (KEY_REVOKED).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-Attribution:
description: 'Always "Prices from Hobby Card Index (https://hobbycardindex.com)" on a successful JSON object response: the credit the data must carry.'
schema:
type: string
X-HCI-Requests-Allowance:
description: 'Commercial plans only: the plan''s monthly requests.'
schema:
type: integer
X-HCI-Plan:
description: 'Commercial plans only: the plan id behind this key.'
schema:
type: string
X-HCI-Requests-Used:
description: 'Commercial plans only: requests used this month, after this one.'
schema:
type: integer
RateLimit-Limit:
description: Requests allowed in the current one-second window (X-RateLimit-* are sent too).
schema:
type: integer
RateLimit-Remaining:
description: Requests left in the current one-second window.
schema:
type: integer
schemas:
Error:
type: object
properties:
success:
type: boolean
const: false
description: false on every error the API itself sends. The per-second rate limiter's 429 body has only `error`.
error:
type: object
properties:
code:
type: string
description: Machine-readable code, for example VALIDATION_ERROR, INVALID_PARAM, MISSING_API_KEY, INVALID_API_KEY, KEY_REVOKED, PLAN_REQUIRED, TRIAL_ENDED, NOT_ON_PLAN, REQUIRES_COMMERCIAL_LICENSE, REQUIRES_GROWTH, REQUIRES_PARTNER_PLAN, RATE_LIMITED, MONTHLY_LIMIT_REACHED, DAILY_LIMIT_REACHED, NOT_FOUND, SERVER_ERROR.
message:
type: string
description: What went wrong and, where there is one, what to do about it.
details:
type: object
additionalProperties: true
description: 'Extra fields on some errors: plans_url, upgrade_url, limit, allowance, plan, upgrade.'
required:
- code
- message
required:
- error
description: The error envelope from every endpoint.
Attribution:
type: object
properties:
text:
type: string
const: Prices from Hobby Card Index
url:
type: string
format: uri
const: https://hobbycardindex.com
html:
type: string
const: <a href="https://hobbycardindex.com" rel="noopener">Prices from Hobby Card Index</a>
description: 'Ready to paste: the credit as a link.'
required:
type: boolean
const: true
terms:
type: string
format: uri
const: https://hobbycardindex.com/terms/
required:
- text
- url
- html
- required
- terms
description: 'The credit this data must carry wherever it is shown: a visible "Prices from Hobby Card Index" link to https://hobbycardindex.com. Added to every successful JSON object response (also sent as the X-Attribution header).'
Usage:
oneOf:
- type: object
properties:
plan:
type: string
const: self-serve
description: 'An Enterprise (or Dealer) key: 1 request a second, licensed for your own business.'
rateLimitPerSecond:
type: integer
dailyCeiling:
type: integer
description: The runaway backstop, requests a day.
required:
- plan
- rateLimitPerSecond
- dailyCeiling
- type: object
properties:
plan:
type: string
description: 'The commercial plan id: trial, lite, growth_lite, growth, platform, or a custom plan.'
label:
type: string
description: The plan as we name it.
month:
type: string
description: The month the counters cover, YYYY-MM (UTC).
requests:
$ref: '#/components/schemas/UsageCounter'
scans:
$ref: '#/components/schemas/UsageCounter'
saleLookups:
type: object
properties:
used:
type:
- integer
- 'null'
description: ''
allowance:
type: integer
description: Plans with sold sales.
certLookups:
type: object
properties:
used:
type:
- integer
- 'null'
description: ''
allowance:
type: integer
description: Plans with cert lookups.
popReports:
type: object
properties:
used:
type:
- integer
- 'null'
description: ''
allowance:
type: integer
description: Plans with pop reports.
features:
type: object
properties:
soldSales:
type: boolean
description: ''
certLookups:
type: boolean
description: ''
priceHistory:
type: boolean
description: ''
population:
type: boolean
description: ''
bulkFiles:
type: boolean
description: ''
perSecond:
type: object
properties:
lookups:
type: integer
scans:
type: integer
certs:
type: integer
overage:
oneOf:
- type: object
properties:
usdPer1000:
type: number
price:
type: string
description: The rate in words, for example $1 per 1,000.
stopsAt:
type: string
description: For example 3x allowance.
billed:
type: string
description: When and how overage is billed.
- type: 'null'
description: null on plans that stop at the allowance.
overageOffer:
type: object
properties:
usdPer1000:
type: number
price:
type: string
stopsAt:
type: string
acceptAt:
type: string
format: uri
description: Present while overage waits on your acceptance of the updated terms.
trialEndsAt:
type:
- string
- 'null'
format: date-time
description: When a free setup month ends; null on paid plans.
bulkFiles:
type: boolean
description: Whether the daily price files are included.
required:
- plan
- label
- month
- requests
- scans
- features
- perSecond
UsageCounter:
type: object
properties:
used:
type:
- integer
- 'null'
description: Used this month (this setup month, on a free setup month with its daily pool lifted).
allowance:
type: integer
description: The plan's monthly number.
usedToday:
type: integer
description: Plans with a daily pool only.
allowancePerDay:
type: integer
description: Plans with a daily pool only.
required:
- used
- allowance
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'Your HobbyCardIndex API key (hci_live_...). `Authorization: Bearer <key>` is accepted too. Keys: https://hobbycardindex.com/developers.'
externalDocs:
description: Developer documentation with examples in curl, JavaScript and Python
url: https://hobbycardindex.com/developers