{
  "openapi": "3.1.0",
  "info": {
    "title": "CollectAIO Public API",
    "summary": "Unauthenticated read-only endpoints for searching, browsing, and retrieving public collectible market data.",
    "description": "This schema documents the public read-only CollectAIO endpoints that are useful to agents and LLMs. Use canonical page URLs when citing results to users. Prices are market estimates or marketplace signals, not guaranteed appraisals.",
    "version": "2026-07-12"
  },
  "externalDocs": {
    "description": "CollectAIO developer guide, citation rules, and embeddable market data",
    "url": "https://www.collectaio.com/developers"
  },
  "servers": [
    {
      "url": "https://www.collectaio.com",
      "description": "CollectAIO production site"
    }
  ],
  "tags": [
    {
      "name": "Search",
      "description": "Find public items and categories."
    },
    {
      "name": "Browse",
      "description": "Navigate public browse categories and category item lists."
    },
    {
      "name": "Items",
      "description": "Retrieve public item market details."
    },
    {
      "name": "Releases",
      "description": "Retrieve public release tracking data."
    }
  ],
  "paths": {
    "/api/v2/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "searchCollectibles",
        "summary": "Search public collectible items and categories.",
        "description": "Returns matching items and categories for a free-text query. Use item and category slugs to build canonical page URLs.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "Search query, such as `pokemon 151`, `lego 75357`, or `topps chrome football`."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 96,
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/search/suggest": {
      "get": {
        "tags": ["Search"],
        "operationId": "suggestCollectibles",
        "summary": "Return lightweight search suggestions.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggested item and category matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/browse/roots": {
      "get": {
        "tags": ["Browse"],
        "operationId": "listBrowseRoots",
        "summary": "List top-level public browse categories.",
        "responses": {
          "200": {
            "description": "Root browse categories.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrowseCategoryListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/browse/public_categories": {
      "get": {
        "tags": ["Browse"],
        "operationId": "listPublicBrowseCategories",
        "summary": "List all public browse categories with item counts.",
        "responses": {
          "200": {
            "description": "Public category directory.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCategoriesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/browse/{slug}": {
      "get": {
        "tags": ["Browse"],
        "operationId": "getBrowseCategory",
        "summary": "Get a public browse category and its child categories.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Browse category slug."
          }
        ],
        "responses": {
          "200": {
            "description": "Category detail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrowseCategoryDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Browse category not found."
          }
        }
      }
    },
    "/api/v2/browse/{slug}/items": {
      "get": {
        "tags": ["Browse"],
        "operationId": "listBrowseCategoryItems",
        "summary": "List public items in a browse category.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Browse category slug."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 96,
              "default": 24
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Optional text filter within the category."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["", "default", "name_asc", "name_desc"]
            }
          },
          {
            "name": "condition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["new_sealed", "used_complete", "loose_complete"]
            },
            "description": "Optional LEGO market-condition filter when supported by the category."
          }
        ],
        "responses": {
          "200": {
            "description": "Category item page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrowseItemsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Browse category not found."
          },
          "503": {
            "description": "Browse temporarily unavailable."
          }
        }
      }
    },
    "/api/v1/items/public": {
      "get": {
        "tags": ["Items"],
        "operationId": "listPublicItemSlugs",
        "summary": "List public item slugs for discovery and sitemap-style pagination.",
        "parameters": [
          {
            "name": "include_meta",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "When true, returns pagination metadata."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 5000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public item slug list. With include_meta=false the response is a bare array of item slug records.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PublicItemsResponse"
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicItemSlug"
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/items/bulk": {
      "get": {
        "tags": ["Items"],
        "operationId": "getItemsBulk",
        "summary": "Fetch many public items by slug.",
        "description": "Supports up to 200 slugs per request. The `slugs`, `slug`, or `ids` query parameter may be used by the backend; prefer `slugs`.",
        "parameters": [
          {
            "name": "slugs",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated item slugs."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching public items in the requested order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items"],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Item"
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "422": {
            "description": "Too many slugs."
          }
        }
      }
    },
    "/api/v1/items/{slug}": {
      "get": {
        "tags": ["Items"],
        "operationId": "getItemBySlug",
        "summary": "Fetch public item market details by slug.",
        "description": "Returns rich market, variation, listing, and price-history data for a public item.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Item slug from search, browse, sitemap, or a canonical item URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Public item detail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "404": {
            "description": "Item not found."
          }
        }
      }
    },
    "/api/v1/release_watch": {
      "get": {
        "tags": ["Releases"],
        "operationId": "listReleaseWatch",
        "summary": "List tracked public release-watch items.",
        "responses": {
          "200": {
            "description": "Release-watch items.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReleaseWatchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/release_watch/standouts": {
      "get": {
        "tags": ["Releases"],
        "operationId": "listReleaseStandouts",
        "summary": "List public release-watch market standouts.",
        "responses": {
          "200": {
            "description": "Release standout payload. Shape may evolve as market signals change.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "required": ["items", "categories", "page", "per_page"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchItem"
            }
          },
          "items_total": {
            "type": "integer"
          },
          "items_total_exact": {
            "type": "boolean"
          },
          "items_total_strategy": {
            "type": "string"
          },
          "items_has_next_page": {
            "type": "boolean"
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchCategory"
            }
          },
          "categories_total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "SuggestResponse": {
        "type": "object",
        "required": ["items", "categories"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchItem"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchCategory"
            }
          }
        },
        "additionalProperties": false
      },
      "SearchItem": {
        "type": "object",
        "required": ["name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "image_url": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "price": {
            "type": ["number", "null"]
          },
          "market_condition": {
            "type": ["string", "null"]
          },
          "release_date": {
            "type": ["string", "null"],
            "format": "date"
          },
          "release_dates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "value_label": {
            "type": ["string", "null"],
            "description": "Human label for the displayed market value, such as CollectAIO Value."
          },
          "value_basis": {
            "type": ["string", "null"],
            "description": "Machine-readable basis for the displayed value, such as sold_fmv, ask_only, tcg_market_fallback, custom, or a source-specific basis."
          },
          "value_basis_label": {
            "type": ["string", "null"],
            "description": "Human-readable basis label, such as Sold comps or Seller asks."
          },
          "value_confidence": {
            "type": ["string", "null"],
            "description": "Confidence label for the displayed value when available."
          },
          "value_source_label": {
            "type": ["string", "null"],
            "description": "Source label behind the displayed value, such as eBay sold comps or TCGPlayer Market."
          },
          "value_sample_size": {
            "type": ["integer", "null"],
            "description": "Number of matched observations behind the displayed value when available."
          },
          "matched_variation_id": {
            "type": ["integer", "null"],
            "description": "Variation id matched by the search query when available."
          },
          "matched_variation_name": {
            "type": ["string", "null"],
            "description": "Variation name matched by the search query when available."
          },
          "primary_browse_category": {
            "$ref": "#/components/schemas/CategoryReference"
          },
          "variation_count": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "SearchCategory": {
        "type": "object",
        "required": ["name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "item_count": {
            "type": "integer"
          },
          "direct_item_count": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "BrowseCategoryListResponse": {
        "type": "object",
        "required": ["categories", "total"],
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BrowseCategory"
            }
          },
          "total": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "PublicCategoriesResponse": {
        "type": "object",
        "required": ["categories", "total"],
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCategory"
            }
          },
          "total": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "BrowseCategoryDetailResponse": {
        "type": "object",
        "required": ["category", "category_path", "categories", "has_children"],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/BrowseCategory"
          },
          "category_path": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CategoryReference"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BrowseCategory"
            }
          },
          "total_children": {
            "type": "integer"
          },
          "view": {
            "type": "string"
          },
          "has_children": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "BrowseItemsResponse": {
        "type": "object",
        "required": ["category", "category_path", "items", "total", "page", "per_page"],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/BrowseCategory"
          },
          "category_path": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CategoryReference"
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BrowseItem"
            }
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "BrowseCategory": {
        "type": "object",
        "required": ["id", "name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "has_children": {
            "type": "boolean"
          },
          "children_count": {
            "type": "integer"
          },
          "direct_item_count": {
            "type": "integer"
          },
          "item_count": {
            "type": "integer"
          },
          "kind": {
            "type": ["string", "null"]
          },
          "browse_mode": {
            "type": ["string", "null"]
          }
        },
        "additionalProperties": true
      },
      "PublicCategory": {
        "type": "object",
        "required": ["id", "name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "item_count": {
            "type": "integer"
          },
          "direct_item_count": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "BrowseItem": {
        "type": "object",
        "required": ["id", "name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "image_url": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "price": {
            "type": ["number", "null"]
          },
          "market_condition": {
            "type": ["string", "null"]
          },
          "release_date": {
            "type": ["string", "null"],
            "format": "date"
          },
          "release_dates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "value_label": {
            "type": ["string", "null"],
            "description": "Human label for the displayed market value, such as CollectAIO Value."
          },
          "value_basis": {
            "type": ["string", "null"],
            "description": "Machine-readable basis for the displayed value, such as sold_fmv, ask_only, tcg_market_fallback, custom, or a source-specific basis."
          },
          "value_basis_label": {
            "type": ["string", "null"],
            "description": "Human-readable basis label, such as Sold comps or Seller asks."
          },
          "value_confidence": {
            "type": ["string", "null"],
            "description": "Confidence label for the displayed value when available."
          },
          "value_source_label": {
            "type": ["string", "null"],
            "description": "Source label behind the displayed value, such as eBay sold comps or TCGPlayer Market."
          },
          "value_sample_size": {
            "type": ["integer", "null"],
            "description": "Number of matched observations behind the displayed value when available."
          },
          "primary_browse_category": {
            "$ref": "#/components/schemas/CategoryReference"
          },
          "variation_count": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "PublicItemsResponse": {
        "type": "object",
        "required": ["items", "page", "per", "total", "pages"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicItemSlug"
            }
          },
          "page": {
            "type": "integer"
          },
          "per": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "PublicItemSlug": {
        "type": "object",
        "required": ["slug"],
        "properties": {
          "slug": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "Item": {
        "type": "object",
        "required": ["id", "name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "upc": {
            "type": ["string", "null"]
          },
          "retail_msrp": {
            "type": ["number", "null"]
          },
          "release_date": {
            "type": ["string", "null"],
            "format": "date"
          },
          "release_dates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "category_path": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CategoryReference"
            }
          },
          "cover_url": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "preferred_image_url": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "source": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "variations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Variation"
            }
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            }
          },
          "listing_summaries": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "daily_prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DailyPrice"
            }
          },
          "related_items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "Variation": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "raw_name": {
            "type": ["string", "null"]
          },
          "display_price": {
            "type": ["number", "null"]
          },
          "pricing_source": {
            "type": ["string", "null"]
          },
          "collectaio_value": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "tcgplayer_market_price": {
            "type": ["number", "null"]
          },
          "stockx_price_signal": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "cardmarket_price_signal": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "grade_scale": {
            "type": ["string", "null"]
          },
          "grade_value": {
            "type": ["number", "null"]
          },
          "grading_provider": {
            "type": ["string", "null"]
          },
          "grade_qualifier": {
            "type": ["string", "null"]
          },
          "is_certified": {
            "type": ["boolean", "null"]
          }
        },
        "additionalProperties": true
      },
      "Listing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": ["string", "null"]
          },
          "price": {
            "type": ["number", "null"]
          },
          "shipping": {
            "type": ["number", "null"]
          },
          "url": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "market_state": {
            "type": ["string", "null"]
          },
          "include_in_price": {
            "type": ["boolean", "null"]
          },
          "sold_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "DailyPrice": {
        "type": "object",
        "properties": {
          "variation_id": {
            "type": "integer"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "price": {
            "type": "number"
          },
          "basis": {
            "type": "string"
          },
          "total_listings": {
            "type": ["integer", "null"]
          },
          "metadata": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "updated_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "ReleaseWatchResponse": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReleaseWatchItem"
            }
          }
        },
        "additionalProperties": false
      },
      "ReleaseWatchItem": {
        "type": "object",
        "required": ["name", "slug"],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "sport": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "lane": {
            "type": "string"
          },
          "marketTrackerOnly": {
            "type": "boolean"
          },
          "dropDate": {
            "type": "string",
            "format": "date"
          },
          "dropDates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "releaseDate": {
            "type": "string",
            "format": "date"
          },
          "releaseDates": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "CategoryReference": {
        "type": ["object", "null"],
        "required": ["name", "slug"],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "x-collectaio-llm-guidance": {
    "canonical_item_url_template": "https://www.collectaio.com/item/{slug}",
    "canonical_category_url_template": "https://www.collectaio.com/category/{slug}",
    "citation_guidance": "Use API data for structured lookup, then cite canonical item or category pages in user-facing answers.",
    "avoid_paths": ["/admin", "/dashboard", "/collections", "/watches", "/account", "/trades"]
  }
}