{ "openapi": "3.1.0", "info": { "title": "HoodCar Data API", "version": "1.1.0", "description": "Graded-card market intelligence — floor snapshots, a daily price index, aggregated sold-comp stats, movers, and per-card HoodCar Value. Derived analytics only.\n\n**Get an API key -> https://hoodcar.com/get-key**\n\nEvery response is a `{ meta, data }` envelope. Authenticate with the `x-api-key` header.", "contact": { "name": "HoodCar", "url": "https://hoodcar.com" }, "termsOfService": "https://hoodcar.com/data" }, "servers": [ { "url": "https://api.hoodcar.com/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "System", "description": "Health and discovery." }, { "name": "Market Data", "description": "Floor, index, sold comps, movers, and value." } ], "paths": { "/ping": { "get": { "tags": [ "System" ], "summary": "Health check", "description": "Liveness probe. No API key required.", "security": [], "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "example": { "ok": true, "service": "hoodcar-data-api", "ts": "2026-06-15T01:37:17.563Z" } } } } } } }, "/categories": { "get": { "tags": [ "System" ], "summary": "Discover categories and labels", "description": "With no parameter, returns every category with counts. Add `?category=` to list that category's labels.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "baseball", "basketball", "football", "soccer", "pokemon", "vintage", "highend", "magic", "misc", "other", "tcg", "yugioh" ] }, "example": "basketball" } ], "responses": { "200": { "description": "Category index, or labels for one category", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CategoriesResponse" }, { "$ref": "#/components/schemas/LabelsResponse" } ] }, "example": { "meta": { "tier": "enterprise", "remaining": 1999991, "generated": "2026-06-15T01:37:17.797Z" }, "data": { "as_of": "2026-06-14", "category": "basketball", "labels": [ { "label": "jordan", "avg": 5270.66, "median": 750, "listings": 333 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/floor": { "get": { "tags": [ "Market Data" ], "summary": "Current floor snapshot", "description": "Current floor per category, as of the latest snapshot date.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "baseball", "basketball", "football", "soccer", "pokemon", "vintage", "highend", "magic", "misc", "other", "tcg", "yugioh" ] }, "example": "basketball" } ], "responses": { "200": { "description": "Floor snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloorResponse" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999990, "generated": "2026-06-15T01:37:18.020Z" }, "data": { "as_of": "2026-06-14", "categories": [ { "category": "basketball", "avg": 1798.2, "median": 497.78, "listings": 2480, "floor_min": 200, "total_value": 5196656.04 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/index": { "get": { "tags": [ "Market Data" ], "summary": "Daily price index time series", "description": "Daily price index per category/label, since 2026-05-29.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "baseball", "basketball", "football", "soccer", "pokemon", "vintage", "highend", "magic", "misc", "other", "tcg", "yugioh" ] }, "example": "pokemon" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2026-05-29" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Index time series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999989, "generated": "2026-06-15T01:37:18.407Z" }, "data": { "series": [ { "date": "2026-05-29", "category": "pokemon", "avg": 1199.34, "median": 521.99, "listings": 528, "floor_min": 200, "total_value": 698226.81 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/sold": { "get": { "tags": [ "Market Data" ], "summary": "Aggregated sold-comp stats", "description": "Derived sold-comp statistics for a card query.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "wembanyama prizm" }, { "name": "grade", "in": "query", "required": false, "schema": { "type": "string" }, "example": "PSA 10" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "example": 90 } ], "responses": { "200": { "description": "Sold-comp stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoldResponse" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999988, "generated": "2026-06-15T01:37:18.944Z" }, "data": { "avg": 1725, "max": 3100, "min": 350, "median": 1725, "sales": 2, "window_days": 90, "by_grade": [ { "grade": "PSA 10", "avg": 1725, "median": 1725, "sales": 2 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/movers": { "get": { "tags": [ "Market Data" ], "summary": "Top movers (beta)", "description": "Labels with the biggest recent change in average price.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "baseball", "basketball", "football", "soccer", "pokemon", "vintage", "highend", "magic", "misc", "other", "tcg", "yugioh" ] }, "example": "soccer" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "example": 5 } ], "responses": { "200": { "description": "Top movers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoversResponse" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999987, "generated": "2026-06-15T01:37:19.175Z" }, "data": { "beta": true, "movers": [ { "label": "messi", "category": "soccer", "current_avg": 2593.08, "prev_avg": 2529.92, "pct_change": 2.5, "direction": "up", "n": 295 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/value": { "get": { "tags": [ "Market Data" ], "summary": "HoodCar Value for a card", "description": "The HoodCar Value for a card query: value + p25/p75 range, min/max, confidence, and a per-grade ladder.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "jordan fleer 57" }, { "name": "grade", "in": "query", "required": false, "schema": { "type": "string" }, "example": "PSA 9" }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number" }, "example": 1000 }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number" }, "example": 50000 } ], "responses": { "200": { "description": "HoodCar Value with range and per-grade ladder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValueResponse" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999986, "generated": "2026-06-30T04:55:00.000Z" }, "data": { "query": "jordan fleer 57", "grade": null, "currency": "USD", "filter": { "min_price": null, "max_price": null }, "sample_size": 57, "value": 6930, "low": 5311, "high": 10720, "min": 1, "max": 35101, "avg": 8642.44, "confidence": 75, "as_of": "2026-06-30T02:14:29.655Z", "by_grade": [ { "grade": "PSA 9", "value": 20244.5, "low": 16762.5, "high": 31767.25, "min": 11059, "max": 35101, "sample_size": 6 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v3/value": { "get": { "tags": [ "Market Data" ], "servers": [ { "url": "https://api.hoodcar.com" } ], "summary": "HoodCar Value + intelligence (enriched)", "description": "Everything in /v1/value PLUS the proprietary intelligence layer: buy_score, verdict, liquidity, confidence, last_sale, sales_90d, and trend. The signals you act on, not just raw stats.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "jordan fleer 57" }, { "name": "grade", "in": "query", "required": false, "schema": { "type": "string" }, "example": "PSA 9" }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Enriched value with intelligence signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValueV3Response" }, "example": { "meta": { "tier": "enterprise", "remaining": 1999980, "generated": "2026-06-30T16:00:00.000Z" }, "data": { "query": "jordan fleer 57", "grade": null, "currency": "USD", "sample_size": 57, "value": 6930, "low": 5311, "high": 10720, "min": 1, "max": 35101, "avg": 8642.44, "confidence": 75, "buy_score": 63, "verdict": "Accumulate", "liquidity": 65, "last_sale": 9400, "last_sale_date": "2026-06-26T01:40:48.700Z", "sales_90d": 13, "trend_30d": null, "population": null, "watchers": null, "by_grade": [ { "grade": "PSA 9", "value": 20244.5, "low": 16762.5, "high": 31767.25, "min": 11059, "max": 35101, "sample_size": 6 } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your key (format hc_live_<48 hex>). Get one at https://hoodcar.com/get-key." } }, "responses": { "Unauthorized": { "description": "Missing, malformed, or inactive key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "missing_or_malformed_key", "hint": "send header x-api-key: hc_live_..." } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "tier": { "type": "string", "example": "enterprise" }, "remaining": { "type": "integer", "description": "Requests left in your monthly quota.", "example": 1999992 }, "generated": { "type": "string", "format": "date-time" } } }, "Ping": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "ts": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "missing_or_malformed_key" }, "hint": { "type": "string", "example": "send header x-api-key: hc_live_..." } } }, "CategoryStat": { "type": "object", "properties": { "category": { "type": "string" }, "labels": { "type": "integer" }, "listings": { "type": "integer" } } }, "LabelStat": { "type": "object", "properties": { "label": { "type": "string" }, "avg": { "type": "number" }, "median": { "type": "number" }, "listings": { "type": "integer" } } }, "FloorRow": { "type": "object", "properties": { "category": { "type": "string" }, "avg": { "type": "number" }, "median": { "type": "number" }, "listings": { "type": "integer" }, "floor_min": { "type": "number" }, "total_value": { "type": "number" } } }, "IndexPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "category": { "type": "string" }, "avg": { "type": "number" }, "median": { "type": "number" }, "listings": { "type": "integer" }, "floor_min": { "type": "number" }, "total_value": { "type": "number" } } }, "GradeStat": { "type": "object", "properties": { "grade": { "type": "string" }, "avg": { "type": "number" }, "median": { "type": "number" }, "sales": { "type": "integer" } } }, "Mover": { "type": "object", "properties": { "label": { "type": "string" }, "category": { "type": "string" }, "current_avg": { "type": "number" }, "prev_avg": { "type": "number" }, "pct_change": { "type": "number" }, "direction": { "type": "string", "enum": [ "up", "down" ] }, "n": { "type": "integer" } } }, "CategoriesResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryStat" } } } } } }, "LabelsResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "category": { "type": "string" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/LabelStat" } } } } } }, "FloorResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/FloorRow" } } } } } }, "IndexResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/IndexPoint" } } } } } }, "SoldResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "avg": { "type": "number" }, "max": { "type": "number" }, "min": { "type": "number" }, "median": { "type": "number" }, "sales": { "type": "integer" }, "window_days": { "type": "integer" }, "by_grade": { "type": "array", "items": { "$ref": "#/components/schemas/GradeStat" } } } } } }, "MoversResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "beta": { "type": "boolean" }, "movers": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } } } } } }, "GradeValue": { "type": "object", "properties": { "grade": { "type": "string" }, "value": { "type": "number" }, "low": { "type": "number" }, "high": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "sample_size": { "type": "integer" } } }, "ValueV3Response": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "query": { "type": "string" }, "grade": { "type": "string" }, "currency": { "type": "string" }, "sample_size": { "type": "integer" }, "value": { "type": "number", "description": "HoodCar Value (median)." }, "low": { "type": "number" }, "high": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "avg": { "type": "number" }, "confidence": { "type": "integer", "description": "0-100 spread-based confidence." }, "buy_score": { "type": "integer", "description": "0-100 buy score." }, "verdict": { "type": "string", "enum": [ "Strong Buy", "Accumulate", "Hold", "Reduce" ], "description": "Plain-English call derived from buy_score." }, "liquidity": { "type": "integer", "description": "0-100 liquidity from sales velocity." }, "last_sale": { "type": "number" }, "last_sale_date": { "type": "string", "format": "date-time" }, "sales_90d": { "type": "integer" }, "trend_30d": { "type": "number" }, "population": { "type": "integer" }, "watchers": { "type": "integer" }, "by_grade": { "type": "array", "items": { "$ref": "#/components/schemas/GradeValue" } } } } } }, "ValueResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "properties": { "query": { "type": "string" }, "grade": { "type": "string" }, "currency": { "type": "string" }, "filter": { "type": "object", "properties": { "min_price": { "type": "number" }, "max_price": { "type": "number" } } }, "sample_size": { "type": "integer" }, "value": { "type": "number" }, "low": { "type": "number" }, "high": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "avg": { "type": "number" }, "confidence": { "type": "integer" }, "as_of": { "type": "string", "format": "date-time" }, "by_grade": { "type": "array", "items": { "$ref": "#/components/schemas/GradeValue" } } } } } } } } }