{"openapi":"3.1.0","info":{"title":"CardSightAI API","description":"High-performance API service for CardSightAI","version":"1.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"ErrorResponseInput":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code for programmatic handling"}},"required":["error","code"]},"BatchOperationErrorInput":{"type":"object","properties":{"index":{"type":"number","description":"Index of the failed item in the request array"},"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Card UUID that failed to process"},"error":{"type":"string","description":"Error message describing why the operation failed"}},"required":["index","cardId","error"]},"ServerMessageInput":{"type":"object","properties":{"type":{"type":"string","enum":["info","warning"],"description":"Message severity level"},"message":{"type":"string","description":"Human-readable message text"}},"required":["type","message"]},"CreateListInput":{"type":"object","properties":{"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the collector who will own this list"},"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}},"required":["collectorId"]},"UpdateListInput":{"type":"object","properties":{"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}}},"ListCardItemInput":{"type":"object","properties":{"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the card to add to the list"}},"required":["cardId"]},"AddCardToListInput":{"anyOf":[{"$ref":"#/components/schemas/ListCardItemInput"},{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/ListCardItemInput"},"description":"Batch of cards to add (max 100)"}]},"ListInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the list"},"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the collector who owns this list"},"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}},"required":["id","collectorId"]},"ListCardInput":{"type":"object","properties":{"id":{"type":"string","description":"Internal ID for the list card"},"listId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the list"},"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the card"}},"required":["id","listId","cardId"]},"PaginatedListsResponseInput":{"type":"object","properties":{"lists":{"type":"array","items":{"$ref":"#/components/schemas/ListInput"},"description":"Array of list entities (want lists, collection goals, etc.)"},"total_count":{"type":"number","description":"Total number of lists matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["lists","total_count","skip","take"]},"PaginatedListCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ListCardInput"},"description":"Array of cards in this list with minimal metadata"},"total_count":{"type":"number","description":"Total number of cards in this list"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["cards","total_count","skip","take"]},"BatchListCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ListCardInput"},"description":"Successfully created cards"},"errors":{"description":"Any errors that occurred during batch creation","type":"array","items":{"$ref":"#/components/schemas/BatchOperationErrorInput"}}},"required":["cards"]},"AddCardsToListResponseInput":{"anyOf":[{"$ref":"#/components/schemas/ListCardInput"},{"$ref":"#/components/schemas/BatchListCardsResponseInput"}]},"CreateCollectorInput":{"type":"object","properties":{"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}}},"UpdateCollectorInput":{"type":"object","properties":{"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}}},"CollectorInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the collector"},"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}},"required":["id"]},"PaginatedCollectorsResponseInput":{"type":"object","properties":{"collectors":{"type":"array","items":{"$ref":"#/components/schemas/CollectorInput"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["collectors","total_count","skip","take"]},"CreateCollectionInput":{"type":"object","properties":{"collectorId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the collector who will own this collection"},"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}},"required":["collectorId"]},"UpdateCollectionInput":{"type":"object","properties":{"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}}},"CollectionCardItemInput":{"type":"object","properties":{"cardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the card to add to the collection"},"parallelId":{"description":"UUID of the card parallel if applicable","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"gradeId":{"description":"UUID of the grade if card is graded","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quantity":{"default":1,"description":"Quantity of this card to add","type":"number","minimum":1},"buyPrice":{"description":"Purchase price (numeric string with up to 2 decimal places)","type":"string"},"buyDate":{"description":"Purchase date in YYYY-MM-DD format","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"sellPrice":{"description":"Listed selling price (numeric string with up to 2 decimal places)","type":"string"},"soldPrice":{"description":"Actual sold price (numeric string with up to 2 decimal places)","type":"string"},"soldDate":{"description":"Sale date in YYYY-MM-DD format","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["cardId"]},"CreateCollectionCardInput":{"anyOf":[{"$ref":"#/components/schemas/CollectionCardItemInput"},{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/CollectionCardItemInput"},"description":"Batch of cards to add (max 100)"}]},"UpdateCollectionCardInput":{"type":"object","properties":{"parallelId":{"description":"UUID of the card parallel (null to remove)","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"gradeId":{"description":"UUID of the grade (null to remove)","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"quantity":{"description":"Updated quantity","type":"number","minimum":1},"buyPrice":{"description":"Purchase price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"buyDate":{"description":"Purchase date (null to remove)","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"sellPrice":{"description":"Listed selling price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"soldPrice":{"description":"Actual sold price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"soldDate":{"description":"Sale date (null to remove)","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}}},"CollectionInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the collection"},"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the collector who owns this collection"},"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}},"required":["id","collectorId"]},"CollectionCardInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the collection card"},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection this card belongs to"},"cardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the card"},"parallelId":{"description":"ID of the card parallel if applicable","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"gradeId":{"description":"UUID of the grade if card is graded","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quantity":{"default":1,"description":"Quantity of this card in the collection","type":"number","minimum":1},"buyPrice":{"description":"Purchase price of the card","type":"string"},"buyDate":{"description":"Date the card was purchased (YYYY-MM-DD)","type":"string"},"sellPrice":{"description":"Listed selling price of the card","type":"string"},"soldPrice":{"description":"Actual sold price of the card","type":"string"},"soldDate":{"description":"Date the card was sold (YYYY-MM-DD)","type":"string"}},"required":["id","collectionId","cardId"]},"PaginatedCollectionsResponseInput":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CollectionInput"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["collections","total_count","skip","take"]},"PaginatedCollectionCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CollectionCardInput"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["cards","total_count","skip","take"]},"BatchCollectionCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CollectionCardInput"},"description":"Successfully created cards"},"errors":{"description":"Any errors that occurred during batch creation","type":"array","items":{"$ref":"#/components/schemas/BatchOperationErrorInput"}}},"required":["cards"]},"AddCollectionCardsResponseInput":{"anyOf":[{"$ref":"#/components/schemas/CollectionCardInput"},{"$ref":"#/components/schemas/BatchCollectionCardsResponseInput"}]},"TopCardInGroupInput":{"type":"object","properties":{"cardId":{"type":"string","description":"Card UUID"},"cardName":{"type":"string","description":"Card name"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"buyPrice":{"description":"Purchase price per card","type":"string"},"quantity":{"type":"number","description":"Quantity in collection"}},"required":["cardId","cardName","setName","releaseName","releaseYear","quantity"]},"CollectionBreakdownSummaryInput":{"type":"object","properties":{"totalGroups":{"type":"number","description":"Total number of groups"},"totalCards":{"type":"number","description":"Total number of cards in collection"},"totalQuantity":{"type":"number","description":"Total quantity including duplicates"},"totalInvested":{"description":"Total amount invested (sum of buy prices)","type":"string"},"groupedBy":{"type":"string","description":"The dimension used for grouping"}},"required":["totalGroups","totalCards","totalQuantity","groupedBy"]},"BreakdownPaginationInput":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of groups"},"skip":{"type":"number","description":"Number of groups skipped"},"take":{"type":"number","description":"Number of groups included"},"page":{"type":"number","description":"Current page number"},"pages":{"type":"number","description":"Total number of pages"}},"required":["total_count","skip","take","page","pages"]},"BreakdownGroupInput":{"type":"object","properties":{"groupKey":{"type":"string","description":"The grouping key (e.g., set name, year, grade)"},"groupId":{"description":"The UUID of the group entity if applicable","type":"string"},"cardCount":{"type":"number","description":"Number of cards in this group"},"uniqueCardCount":{"type":"number","description":"Number of unique cards (ignoring duplicates)"},"totalQuantity":{"type":"number","description":"Total quantity including duplicates"},"totalBuyPrice":{"description":"Total purchase price for cards in group","type":"string"},"totalSoldPrice":{"description":"Total sold price for sold cards","type":"string"},"averageBuyPrice":{"description":"Average purchase price per card","type":"string"},"percentageOfCollection":{"type":"number","description":"Percentage this group represents of total collection"},"topCards":{"description":"Top cards in this group","type":"array","items":{"$ref":"#/components/schemas/TopCardInGroupInput"}}},"required":["groupKey","cardCount","uniqueCardCount","totalQuantity","percentageOfCollection"]},"CollectionBreakdownResponseInput":{"type":"object","properties":{"summary":{"description":"Aggregate statistics across all groups","$ref":"#/components/schemas/CollectionBreakdownSummaryInput"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownGroupInput"},"description":"Array of breakdown groups"},"pagination":{"description":"Pagination metadata","$ref":"#/components/schemas/BreakdownPaginationInput"}},"required":["summary","groups","pagination"]},"SetProgressInput":{"type":"object","properties":{"setId":{"type":"string","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"totalCards":{"type":"number","description":"Total number of cards in set"},"ownedCards":{"type":"number","description":"Number of unique cards owned"},"missingCards":{"type":"array","items":{"type":"string"},"description":"Array of missing card UUIDs"},"completionPercentage":{"type":"number","description":"Percentage complete (0-100)"},"difficultyScore":{"description":"Difficulty score based on card availability (0-100)","type":"number"}},"required":["setId","setName","releaseName","releaseYear","totalCards","ownedCards","missingCards","completionPercentage"]},"SetProgressSummaryInput":{"type":"object","properties":{"totalSets":{"type":"number","description":"Total number of sets represented in collection"},"nearCompleteSets":{"type":"number","description":"Number of sets >80% complete"},"fullyCompleteSets":{"type":"number","description":"Number of fully complete sets"}},"required":["totalSets","nearCompleteSets","fullyCompleteSets"]},"SetProgressListResponseInput":{"type":"object","properties":{"summary":{"description":"Aggregate statistics across all sets","$ref":"#/components/schemas/SetProgressSummaryInput"},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetProgressInput"},"description":"Array of set progress entries"},"total_count":{"type":"number","description":"Total number of sets matching filters"},"skip":{"type":"number","description":"Number of records skipped"},"take":{"type":"number","description":"Number of records returned"}},"required":["summary","sets","total_count","skip","take"]},"ParallelSetProgressInput":{"type":"object","properties":{"setId":{"type":"string","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"parallelId":{"type":"string","description":"Parallel UUID"},"parallelName":{"type":"string","description":"Parallel name (e.g., Refractor, Gold)"},"totalCards":{"type":"number","description":"Total number of cards in set"},"ownedCards":{"type":"number","description":"Number of this parallel owned"},"missingCards":{"type":"array","items":{"type":"string"},"description":"Array of missing card UUIDs for this parallel"},"completionPercentage":{"type":"number","description":"Percentage complete for this parallel (0-100)"}},"required":["setId","setName","releaseName","releaseYear","parallelId","parallelName","totalCards","ownedCards","missingCards","completionPercentage"]},"CollectionOverviewInput":{"type":"object","properties":{"totalCards":{"type":"number","description":"Total number of card entries in collection"},"uniqueCards":{"type":"number","description":"Number of unique cards (ignoring duplicates)"},"totalQuantity":{"type":"number","description":"Total quantity including all duplicates"}},"required":["totalCards","uniqueCards","totalQuantity"]},"CollectionFinancialsInput":{"type":"object","properties":{"totalInvested":{"description":"Total amount invested (sum of buy prices)","type":"string"},"totalRealizedGains":{"description":"Total gains from sold cards (soldPrice - buyPrice)","type":"string"}}},"CollectionCompositionInput":{"type":"object","properties":{"gradedCount":{"type":"number","description":"Number of graded cards"},"rawCount":{"type":"number","description":"Number of raw (ungraded) cards"},"gradedPercentage":{"type":"number","description":"Percentage of collection that is graded"},"forSaleCount":{"type":"number","description":"Number of cards listed for sale"},"soldCount":{"type":"number","description":"Number of cards that have been sold"}},"required":["gradedCount","rawCount","gradedPercentage","forSaleCount","soldCount"]},"CollectionAnalyticsResponseInput":{"type":"object","properties":{"overview":{"description":"Collection overview with basic counts","$ref":"#/components/schemas/CollectionOverviewInput"},"financials":{"description":"Investment and return metrics based on user-entered buy/sell data","$ref":"#/components/schemas/CollectionFinancialsInput"},"composition":{"description":"Breakdown of collection by type and status","$ref":"#/components/schemas/CollectionCompositionInput"}},"required":["overview","financials","composition"]},"UploadCollectionCardImageResponseInput":{"type":"object","properties":{"imageId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the image record"},"uploadedAt":{"type":"string","description":"Timestamp when the image was uploaded"},"fullImageUrl":{"type":"string","description":"URL to retrieve the full-resolution image"},"thumbnailUrl":{"type":"string","description":"URL to retrieve the thumbnail image"}},"required":["imageId","uploadedAt","fullImageUrl","thumbnailUrl"]},"CreateBinderInput":{"type":"object","properties":{"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}}},"UpdateBinderInput":{"type":"object","properties":{"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}}},"AddCardToBinderInput":{"type":"object","properties":{"collectionCardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the collection card to add to the binder"}},"required":["collectionCardId"]},"BinderInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the binder"},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection this binder belongs to"},"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}},"required":["id","collectionId"]},"BinderCardInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the binder card link"},"binderId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the binder"},"collectionCardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection card"}},"required":["id","binderId","collectionCardId"]},"PaginatedBindersResponseInput":{"type":"object","properties":{"binders":{"type":"array","items":{"$ref":"#/components/schemas/BinderInput"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["binders","total_count","skip","take"]},"PaginatedBinderCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/BinderCardInput"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["cards","total_count","skip","take"]},"FeedbackInputInput":{"type":"object","properties":{"feedback_type":{"description":"Category of feedback. Accepted values: data_error (incorrect data), missing_data (something is missing from the catalog), suggestion (improvement idea), bug (something is broken), other (does not fit other categories)","type":"string","enum":["data_error","missing_data","suggestion","bug","other"]},"message":{"type":"string","minLength":1,"maxLength":1000,"description":"Detailed description of the feedback. Include specifics such as what is wrong, what you expected, or what you suggest. Max 1000 characters."}},"required":["message"]},"FeedbackResponseInput":{"type":"object","properties":{"unique_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for this feedback submission"},"entity_type":{"type":"string","enum":["release","set","card","product","manufacturer","segment","general","identify"],"description":"The type of entity this feedback is about"},"entity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The unique ID of the entity, or null for general feedback"},"feedback_type":{"anyOf":[{"type":"string","enum":["data_error","missing_data","suggestion","bug","other"],"description":"FeedbackType"},{"type":"null"}],"description":"The category of feedback submitted"},"message":{"type":"string","description":"The feedback message"},"status":{"type":"string","enum":["not_reviewed","under_review","fixed","wont_fix","duplicate","need_info"],"description":"Current review status of the feedback"},"created_at":{"type":"string","description":"ISO 8601 timestamp when the feedback was submitted"},"updated_at":{"type":"string","description":"ISO 8601 timestamp when the feedback was last updated"}},"required":["unique_id","entity_type","entity_id","feedback_type","message","status","created_at","updated_at"]},"FeedbackSubmitResponseInput":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/FeedbackResponseInput"}},"required":["success","message","data"]},"FileUploadInput":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"The image file to analyze"}},"required":["image"]},"FieldValueInput":{"type":"object","properties":{"key":{"type":"string","description":"Field key (e.g., \"HP\", \"Rarity\", \"Artist\")"},"value":{"type":"string","description":"Field value for the given key"}},"required":["key","value"]},"FieldValuesInput":{"type":"array","items":{"$ref":"#/components/schemas/FieldValueInput"}},"CardSuggestionInput":{"type":"object","properties":{"id":{"description":"UUID of the suggested card","type":"string"},"setName":{"description":"Set name for the suggested card","type":"string"},"fields":{"description":"Key-value field properties for the suggested card. Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValuesInput"}}},"CardDetailsInput":{"type":"object","properties":{"id":{"description":"UUID of the identified card. Present only for exact card matches.","type":"string"},"segmentId":{"description":"UUID of the segment. Present for both exact card and set-level matches.","type":"string"},"releaseId":{"description":"UUID of the release. Present for both exact card and set-level matches.","type":"string"},"setId":{"description":"UUID of the set. Present for both exact card and set-level matches.","type":"string"},"year":{"description":"Release year from catalog (e.g., \"2023\", \"1989\")","type":"string"},"manufacturer":{"description":"Card manufacturer from catalog (e.g., \"Topps\", \"Panini\", \"Upper Deck\")","type":"string"},"releaseName":{"description":"Release/product name from catalog (e.g., \"Topps Chrome\", \"Prizm Basketball\")","type":"string"},"setName":{"description":"Set name from catalog (e.g., \"Base Set\", \"Rookie Variations\")","type":"string"},"name":{"description":"Player or subject name. Present only for exact card matches.","type":"string"},"number":{"description":"Card number. Present only for exact card matches.","type":"string"},"description":{"description":"Descriptive text for the card when available. Omitted if no description exists.","type":"string"},"numberedTo":{"description":"Print run for numbered cards (e.g., 25 for a /25 card). Omitted if the card is not numbered.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attributes":{"description":"Notable attributes of the card (e.g., [\"Rookie\", \"Autograph\"]). Omitted if the card has no attributes.","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the parent card when this card is a variation. Omitted if the card is not a variation.","type":"string"},"parallel":{"description":"Parallel variant info. Present only for exact card matches with an identified parallel.","$ref":"#/components/schemas/ParallelSummaryInput"},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValuesInput"},"suggestions":{"description":"Alternative card matches when multiple reprints score similarly. Omitted when there are no suggestions.","type":"array","items":{"$ref":"#/components/schemas/CardSuggestionInput"}}}},"IdentificationDataInput":{"type":"object","properties":{"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"AI confidence level for this detection (High: 90-100%, Medium: 75-89%, Low: 50-74%)"},"card":{"description":"Identified card details. Completeness reflects match level: full fields for exact card match, set-level fields for set match, empty object for unmatched detection.","$ref":"#/components/schemas/CardDetailsInput"},"grading":{"description":"Grading slab data matched to this specific card detection. Present when the card is inside a graded slab.","$ref":"#/components/schemas/SlabGradingDetailInput"}},"required":["confidence","card"]},"IdentifyCardResponseInput":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the identification process completed successfully"},"requestId":{"type":"string","description":"Unique identifier for tracking this identification request"},"detections":{"description":"Array of card detections from the image. Multiple cards may be detected in a single image. Each detection may include grading data if the card is inside a graded slab. Empty if no cards found.","type":"array","items":{"$ref":"#/components/schemas/IdentificationDataInput"}},"processingTime":{"description":"Total processing time in milliseconds for AI analysis and catalog matching","type":"number"},"messages":{"description":"Server advisory messages (e.g., image quality warnings)","type":"array","items":{"$ref":"#/components/schemas/ServerMessageInput"}}},"required":["success","requestId"]},"DetectCardResponseInput":{"type":"object","properties":{"detected":{"type":"boolean","description":"Whether one or more trading cards were detected in the image"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of trading cards detected in the image"},"requestId":{"type":"string","description":"Unique identifier for tracking this detection request"},"processingTime":{"type":"number","description":"Total processing time in milliseconds"},"messages":{"description":"Server advisory messages (e.g., image quality warnings)","type":"array","items":{"$ref":"#/components/schemas/ServerMessageInput"}}},"required":["detected","count","requestId","processingTime"]},"SlabCompanyInput":{"type":"object","properties":{"id":{"description":"UUID of the grading company from the catalog. Absent if company could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Grading company name detected on the slab (e.g., \"PSA\", \"BGS\", \"CGC\", \"SGC\")"}},"required":["name"]},"SlabGradeInput":{"type":"object","properties":{"id":{"description":"UUID of the grade from the catalog. Absent if grade could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"value":{"description":"Grade value detected on the slab label","type":"string"},"condition":{"description":"Grade condition detected on the slab label","type":"string"}}},"SlabQualifierInput":{"type":"object","properties":{"id":{"description":"UUID of the qualifier from the catalog. Absent if qualifier could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"code":{"type":"string","description":"Qualifier code (e.g., OC, MC, PD, ST)"}},"required":["code"]},"SlabAutoGradeInput":{"type":"object","properties":{"id":{"description":"UUID of the autograph grade from the catalog. Absent if not matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"value":{"description":"Autograph grade value","type":"string"},"condition":{"description":"Autograph grade condition","type":"string"}}},"SlabGradingDetailInput":{"type":"object","properties":{"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"Detection confidence level for this slab (High: 90-100%, Medium: 75-89%, Low: 50-74%)"},"company":{"description":"Grading company that issued this slab","$ref":"#/components/schemas/SlabCompanyInput"},"grade":{"description":"Grade detected on the slab label","$ref":"#/components/schemas/SlabGradeInput"},"qualifier":{"description":"Defect qualifier detected on the slab label","$ref":"#/components/schemas/SlabQualifierInput"},"autoGrade":{"description":"Autograph grade detected on the slab label","$ref":"#/components/schemas/SlabAutoGradeInput"}},"required":["confidence","company"]},"AIQueryRequestInput":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language query"},"context":{"description":"Optional context for the query","$ref":"#/components/schemas/AIContextInput"},"conversationHistory":{"description":"Optional conversation history (max 50 messages). Messages should alternate between user and assistant roles.","maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageInput"}},"maxIterations":{"description":"Maximum tool use iterations (default: 5)","type":"integer","minimum":1,"maximum":10}},"required":["query"]},"AIContextInput":{"type":"object","properties":{"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"userId":{"type":"string"}},"additionalProperties":{}},"ConversationMessageInput":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"The role of the message sender"},"content":{"type":"string","minLength":1,"maxLength":10000,"description":"The message content"}},"required":["role","content"]},"AIQueryResponseInput":{"type":"object","properties":{"answer":{"type":"string","description":"AI-generated response to the query"},"toolsUsed":{"description":"List of MCP tools used to answer the query","type":"array","items":{"type":"string"}},"processingTime":{"type":"number","description":"Time taken to process the query in milliseconds"}},"required":["answer","processingTime"]},"AIErrorInput":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error","code"]},"ApiKeyUsageInput":{"type":"object","properties":{"key":{"type":"string","description":"The API key (masked or full depending on context)"},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total number of API calls made using this key for the current billing period"}},"required":["key","calls"]},"SubscriptionInfoInput":{"type":"object","properties":{"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total aggregate number of API calls made across all API keys for the current billing period"},"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyUsageInput"},"description":"Array containing usage information for the current API key only"}},"required":["calls","api_keys"]},"ImageJsonResponseInput":{"type":"object","properties":{"data":{"type":"string","description":"Base64 data URI (ready for use in HTML img src)"},"contentType":{"type":"string","description":"MIME type of the image"},"size":{"description":"Size of the image in bytes","type":"number"}},"required":["data","contentType"]},"SegmentInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the segment. Format: UUID v4. This ID is permanent and used for all API operations involving this segment."},"name":{"type":"string","description":"Display name of the segment. Examples: \"Sports\", \"Entertainment\", \"Gaming\". Used for categorizing releases and filtering."},"is_identifiable":{"type":"boolean","description":"Whether cards in this segment can be identified by the CardSightAI identification service."}},"required":["id","name","is_identifiable"]},"ManufacturerInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the manufacturer. Format: UUID v4. This ID is permanent and used for all API operations involving this manufacturer."},"name":{"type":"string","description":"Official name of the manufacturer. Examples: \"Topps\", \"Panini America\", \"Upper Deck\". This is the primary display name."},"description":{"description":"Additional information about the manufacturer, such as founding year, headquarters, or notable product lines. May be null if not provided.","type":"string"}},"required":["id","name"]},"ReleaseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable"]},"SetInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this set belongs to. Links to the release entity. A release typically contains multiple sets."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."}},"required":["id","releaseId","name","is_identifiable"]},"CardInput":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"}},"required":["releaseId","setId","id","name"]},"ParallelInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this parallel belongs to. Links to the set entity. Each set can have multiple parallel types."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true}},"required":["id","setId","name"]},"AttributeInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"}},"required":["id","name","shortName"]},"FieldInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"}},"required":["id","key","name"]},"ParallelSummaryInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"},"cards":{"description":"Card UUIDs that have this parallel. Only present when isPartial is true.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}}},"required":["id","name"]},"AttributeSummaryInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"},"cardCount":{"type":"number","description":"Number of cards with this attribute"}},"required":["id","name","shortName","cardCount"]},"FieldSummaryInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"},"usageCount":{"type":"number","description":"Total number of catalog entities (cards, sets, releases, and segments) that have a value for this field."}},"required":["id","key","name","usageCount"]},"ReleaseSummaryInput":{"type":"object","properties":{"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"description":{"type":"string"}},"required":["manufacturerId","segmentId","id","year","name","is_identifiable"]},"SetSummaryWithCountsInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"}},"required":["id","name","is_identifiable","cardCount","parallelCount"]},"CardSummaryInput":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"setName":{"type":"string","description":"Name of the set this card belongs to"},"releaseName":{"description":"Name of the release","type":"string"},"releaseYear":{"description":"Year of the release","type":"string"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallels":{"description":"Simplified list of parallel variants for this card. Includes id, name, and numberedTo.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"}},"required":["id","name"]}},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["releaseId","setId","id","name","setName"]},"DetailedCardInput":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"setName":{"type":"string","description":"Name of the set"},"numberedTo":{"description":"Limited print run number for this specific card","type":"number"},"parallelCount":{"type":"number","description":"Number of parallel variants for this card"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummaryInput"},"description":"List of parallel variants available for this card"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"fields":{"description":"Key-value field properties inherited from segment, release, set, and card levels (e.g., HP, Rarity, Artist). Additive — duplicate keys across levels are preserved. Omitted when no fields apply anywhere in the lineage.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["releaseId","setId","id","name","setName","parallelCount","parallels"]},"ReleaseWithSetsInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetSummaryWithCountsInput"},"description":"Sets within this release"},"fields":{"description":"Key-value field properties inherited from segment and release levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable","sets"]},"ParallelWithSetInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"},"cards":{"description":"Card UUIDs that have this parallel. Only present when isPartial is true.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"cardCount":{"type":"number","description":"Number of base cards in the set"}},"required":["id","name","setId","setName","releaseId","releaseName","releaseYear","cardCount"]},"PaginatedSegmentsResponseInput":{"type":"object","properties":{"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentInput"},"description":"Array of market segment entities (e.g., Sports, Entertainment, Gaming)"},"total_count":{"type":"number","description":"Total number of segments matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["segments","total_count","skip","take"]},"PaginatedManufacturersResponseInput":{"type":"object","properties":{"manufacturers":{"type":"array","items":{"$ref":"#/components/schemas/ManufacturerInput"},"description":"Array of card manufacturer entities (e.g., Topps, Panini, Upper Deck)"},"total_count":{"type":"number","description":"Total number of manufacturers matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["manufacturers","total_count","skip","take"]},"PaginatedReleasesResponseInput":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummaryInput"},"description":"Array of release entities with summary information (e.g., \"2023 Topps Chrome Baseball\")"},"total_count":{"type":"number","description":"Total number of releases matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["releases","total_count","skip","take"]},"DetailedReleaseResponseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetSummaryWithCountsInput"},"description":"Sets within this release"},"fields":{"description":"Key-value field properties inherited from segment and release levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable","sets"]},"PaginatedCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardSummaryInput"},"description":"Array of card entities with summary information"},"total_count":{"type":"number","description":"Total number of cards matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["cards","total_count","skip","take"]},"PaginatedSetsResponseInput":{"type":"object","properties":{"sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"}},"required":["id","name","is_identifiable","cardCount","parallelCount","releaseId","releaseName","releaseYear"]},"description":"Array of set entities with card counts and release information"},"total_count":{"type":"number","description":"Total number of sets matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["sets","total_count","skip","take"]},"DetailedSetResponseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this set belongs to. Links to the release entity. A release typically contains multiple sets."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"cardCount":{"type":"number","description":"Number of base cards"},"parallelCount":{"type":"number","description":"Number of parallel types"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummaryInput"},"description":"List of parallel variants in this set"},"fields":{"description":"Key-value field properties inherited from segment, release, and set levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["id","releaseId","name","is_identifiable","releaseName","releaseYear","cardCount","parallelCount","parallels"]},"DetailedCardResponseInput":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"setName":{"type":"string","description":"Name of the set"},"numberedTo":{"description":"Limited print run number for this specific card","type":"number"},"parallelCount":{"type":"number","description":"Number of parallel variants for this card"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummaryInput"},"description":"List of parallel variants available for this card"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"fields":{"description":"Key-value field properties inherited from segment, release, set, and card levels (e.g., HP, Rarity, Artist). Additive — duplicate keys across levels are preserved. Omitted when no fields apply anywhere in the lineage.","$ref":"#/components/schemas/FieldValuesInput"}},"required":["releaseId","setId","id","name","setName","parallelCount","parallels"]},"PaginatedAttributesResponseInput":{"type":"object","properties":{"attributes":{"type":"array","items":{"$ref":"#/components/schemas/DetailedAttributeResponseInput"},"description":"Array of card attribute entities (e.g., Rookie Card, Autograph, Memorabilia)"},"total_count":{"type":"number","description":"Total number of attributes matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["attributes","total_count","skip","take"]},"DetailedAttributeResponseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"},"cardCount":{"type":"number","description":"Number of cards with this attribute"}},"required":["id","name","shortName","cardCount"]},"PaginatedFieldsResponseInput":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/DetailedFieldResponseInput"},"description":"Array of field definitions with total usage counts across cards, sets, releases, and segments"},"total_count":{"type":"number","description":"Total number of fields matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["fields","total_count","skip","take"]},"DetailedFieldResponseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"},"usageCount":{"type":"number","description":"Total number of catalog entities (cards, sets, releases, and segments) that have a value for this field."}},"required":["id","key","name","usageCount"]},"PaginatedParallelsResponseInput":{"type":"object","properties":{"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelWithSetInput"},"description":"Array of parallel variants with associated set information (e.g., Refractor, Prizm, numbered parallels)"},"total_count":{"type":"number","description":"Total number of parallels matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["parallels","total_count","skip","take"]},"DetailedParallelResponseInput":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\"."},"description":{"description":"Additional details about the parallel such as special features or visual description. May be null.","type":"string"},"numberedTo":{"description":"Limited print run number. Example: 50 means /50 parallel. Null for unlimited parallels.","type":"number"},"isPartial":{"type":"boolean","description":"True if this parallel applies to specific cards only (e.g., cards 1-400 of a 800-card set). False if it applies to the entire set."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this parallel belongs to."},"setName":{"type":"string","description":"Name of the set this parallel belongs to."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release containing this parallel's set."},"releaseName":{"type":"string","description":"Name of the release (e.g., \"2023 Topps Chrome Baseball\")."},"releaseYear":{"type":"string","description":"Year the release was issued (e.g., \"2023\")."},"cards":{"description":"Array of card UUIDs that have this parallel variant. Only present when isPartial=true. Empty array if partial but no cards mapped.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}}},"required":["id","name","isPartial","setId","setName","releaseId","releaseName","releaseYear"]},"CatalogSegmentBreakdownItemInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Segment unique identifier"},"name":{"type":"string","description":"Segment name"},"count":{"type":"number","description":"Number of releases in this segment"}},"required":["id","name","count"]},"CatalogSegmentStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total number of segments"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSegmentBreakdownItemInput"},"description":"Breakdown of segments with release counts"}},"required":["total","breakdown"]},"CatalogManufacturerBreakdownItemInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Manufacturer unique identifier"},"name":{"type":"string","description":"Manufacturer name"},"releaseCount":{"type":"number","description":"Number of releases by this manufacturer"}},"required":["id","name","releaseCount"]},"CatalogManufacturerStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total number of manufacturers"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CatalogManufacturerBreakdownItemInput"},"description":"All manufacturers with their release counts"}},"required":["total","breakdown"]},"CatalogReleaseYearBreakdownInput":{"type":"object","properties":{"year":{"type":"string","description":"Release year"},"count":{"type":"number","description":"Number of releases in this year for this segment"}},"required":["year","count"]},"CatalogReleaseBySegmentInput":{"type":"object","properties":{"segmentName":{"type":"string","description":"Segment name"},"total":{"type":"number","description":"Total releases in this segment across all years"},"byYear":{"type":"array","items":{"$ref":"#/components/schemas/CatalogReleaseYearBreakdownInput"},"description":"Year-by-year breakdown for this segment"}},"required":["segmentName","total","byYear"]},"CatalogReleaseStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total number of releases across all years"},"bySegment":{"type":"array","items":{"$ref":"#/components/schemas/CatalogReleaseBySegmentInput"},"description":"Breakdown by segment, then by year"}},"required":["total","bySegment"]},"CatalogSetStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total number of card sets"},"identifiable":{"type":"number","description":"Number of sets that can be recognized by AI"}},"required":["total","identifiable"]},"CatalogCardStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total cards including all parallel versions"},"base":{"type":"number","description":"Base cards (non-parallel, non-variation)"},"variations":{"type":"number","description":"Variation cards (non-parallel)"},"parallels":{"type":"number","description":"Total parallel card instances"}},"required":["total","base","variations","parallels"]},"CatalogParallelStatsInput":{"type":"object","properties":{"total":{"type":"number","description":"Total number of parallel types"},"fullSet":{"type":"number","description":"Count of full set parallels (apply to entire set)"},"partial":{"type":"number","description":"Count of partial parallels (apply to specific cards only)"}},"required":["total","fullSet","partial"]},"CatalogStatisticsResponseInput":{"type":"object","properties":{"segments":{"description":"Segment statistics","$ref":"#/components/schemas/CatalogSegmentStatsInput"},"manufacturers":{"description":"Manufacturer statistics","$ref":"#/components/schemas/CatalogManufacturerStatsInput"},"releases":{"description":"Release statistics","$ref":"#/components/schemas/CatalogReleaseStatsInput"},"sets":{"description":"Set statistics","$ref":"#/components/schemas/CatalogSetStatsInput"},"cards":{"description":"Card statistics","$ref":"#/components/schemas/CatalogCardStatsInput"},"parallels":{"description":"Parallel statistics","$ref":"#/components/schemas/CatalogParallelStatsInput"}},"required":["segments","manufacturers","releases","sets","cards","parallels"]},"CardWithOptionalParallelInput":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"setName":{"type":"string","description":"Name of the set this card belongs to"},"releaseName":{"description":"Name of the release","type":"string"},"releaseYear":{"description":"Year of the release","type":"string"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallels":{"description":"Simplified list of parallel variants for this card. Includes id, name, and numberedTo.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"}},"required":["id","name"]}},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValuesInput"},"isParallel":{"description":"True if this card was converted to a parallel variant through the random odds system","type":"boolean"},"parallelId":{"description":"UUID of the parallel type if this card is a parallel variant","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallelName":{"description":"Name of the parallel variant (e.g., \"Gold Refractor\", \"Black Prizm 1/1\")","type":"string"},"numberedTo":{"description":"Limited print run number for this parallel. Null for unlimited parallels.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["releaseId","setId","id","name","setName"]},"RandomReleasesResponseInput":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummaryInput"},"description":"Array of random releases matching the specified filters"},"count":{"type":"number","description":"Actual number of releases returned. May be less than requested count if insufficient matches."}},"required":["releases","count"]},"RandomSetsResponseInput":{"type":"object","properties":{"sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"}},"required":["id","name","is_identifiable","cardCount","parallelCount","releaseId","releaseName","releaseYear"]},"description":"Array of random sets matching the specified filters"},"count":{"type":"number","description":"Actual number of sets returned. May be less than requested count if insufficient matches."}},"required":["sets","count"]},"RandomCardsResponseInput":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardWithOptionalParallelInput"},"description":"Array of random cards. When includeParallels=true, some cards may be converted to parallels based on weighted probability."},"count":{"type":"number","description":"Actual number of cards returned. May be less than requested count if insufficient matches."}},"required":["cards","count"]},"SearchResultInput":{"type":"object","properties":{"type":{"type":"string","enum":["card","set","release","parallel"],"description":"Entity type of this search result."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier (UUID) for this entity. Use this ID to fetch full details from the corresponding entity endpoint."},"name":{"type":"string","description":"Primary name of the entity. Player/subject name for cards, set name for sets, release name for releases."},"relevance":{"type":"number","description":"Relevance score combining full-text search rank and fuzzy similarity. Higher values indicate stronger matches. Results are sorted by this score descending."},"year":{"description":"Release year associated with this result.","type":"string"},"setName":{"description":"Set name. Present for card and parallel results.","type":"string"},"releaseName":{"description":"Release name. Present for card, set, and parallel results.","type":"string"},"manufacturerName":{"description":"Manufacturer name.","type":"string"},"parallelName":{"description":"Name of the matching parallel variant. Present when a parallel name contributed to this result's relevance.","type":"string"}},"required":["type","id","name","relevance"]},"CatalogSearchResponseInput":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResultInput"},"description":"Array of search results ordered by relevance score (descending). Contains a mix of cards, sets, and releases unless filtered by type."},"total_count":{"type":"number","description":"Total number of results matching the query across all included types."},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination."},"take":{"type":"number","description":"Number of results included in this page."}},"required":["results","total_count","skip","take"]},"AutocompleteResponseInput":{"type":"object","properties":{"suggestions":{"maxItems":10,"type":"array","items":{"type":"string"},"description":"List of autocomplete suggestions, maximum 10 items, sorted alphabetically"}},"required":["suggestions"]},"GradingCompanyInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grading company"},"name":{"type":"string","description":"Name of the grading company (e.g., PSA, BGS, SGC, CGC)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detailed description of the grading company and its services"}},"required":["id","name","description"]},"GradingTypeInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grading type"},"gradingCompanyId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the parent grading company offering this grading type"},"gradingCompanyName":{"type":"string","description":"Name of the parent grading company (denormalized for convenience)"},"name":{"type":"string","description":"Name of the grading type (e.g., Regular, Crossover, Black Label)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detailed description of what this grading type offers or represents"}},"required":["id","gradingCompanyId","gradingCompanyName","name","description"]},"GradeInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grade"},"gradingTypeId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the parent grading type that this grade belongs to"},"gradingTypeName":{"type":"string","description":"Name of the parent grading type (denormalized for convenience)"},"gradingCompanyId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the grading company (denormalized for convenience)"},"gradingCompanyName":{"type":"string","description":"Name of the grading company (denormalized for convenience)"},"grade":{"type":"string","description":"The grade value as a string (e.g., \"10\", \"9.5\", \"8\") to support decimal and \"Authentic\" grades"},"condition":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The condition descriptor for this grade (e.g., \"GEM MINT\", \"MINT\", \"PRISTINE\")"}},"required":["id","gradingTypeId","gradingTypeName","gradingCompanyId","gradingCompanyName","grade","condition"]},"GradingCompaniesResponseInput":{"type":"object","properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/GradingCompanyInput"},"description":"List of grading companies"},"total":{"type":"number","description":"Total number of grading companies available"}},"required":["companies","total"]},"GradingTypesResponseInput":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/GradingTypeInput"},"description":"List of grading types offered by this company"},"total":{"type":"number","description":"Total number of grading types for this company"},"gradingCompany":{"description":"Parent grading company information for context","$ref":"#/components/schemas/GradingCompanyInput"}},"required":["types","total","gradingCompany"]},"GradesResponseInput":{"type":"object","properties":{"grades":{"type":"array","items":{"$ref":"#/components/schemas/GradeInput"},"description":"List of specific grade values available for this grading type"},"total":{"type":"number","description":"Total number of grades for this grading type"},"gradingType":{"description":"Parent grading type information for context","$ref":"#/components/schemas/GradingTypeInput"},"gradingCompany":{"description":"Grandparent grading company information for context","$ref":"#/components/schemas/GradingCompanyInput"}},"required":["grades","total","gradingType","gradingCompany"]},"BulkPricingRequestInput":{"type":"object","properties":{"card_ids":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Array of card UUIDs to fetch pricing for (1-100). Matches the max page size of catalog search results."},"parallel_id":{"description":"Filter by parallel variant UUID. null = base card only.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"grade_id":{"description":"Filter by grade UUID. null = ungraded only.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"period":{"default":"all","description":"Lookback period. Examples: \"7d\", \"14d\", \"2w\", \"3m\", \"1y\", \"all\". Omit or \"all\" for no time limit.","type":"string"},"listing_type":{"default":"both","description":"Filter by listing type. auction=completed auctions, fixed=buy-it-now, both=all","type":"string","enum":["auction","fixed","both"]},"limit":{"description":"Maximum number of records per card","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["card_ids"]},"PricingRecordInput":{"type":"object","properties":{"title":{"description":"Listing title from marketplace","anyOf":[{"type":"string"},{"type":"null"}]},"price":{"type":"number","minimum":0,"description":"Sale price in USD"},"date":{"description":"Sale date in ISO 8601 format","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","description":"Data source (e.g., \"ebay\")"},"listing_type":{"description":"Type of listing: auction or fixed price","anyOf":[{"type":"string","enum":["auction","fixed"]},{"type":"null"}]},"url":{"description":"URL to the original listing","anyOf":[{"type":"string"},{"type":"null"}]},"image_url":{"description":"Primary image URL for the listing","anyOf":[{"type":"string"},{"type":"null"}]},"parallel_id":{"description":"Parallel variant UUID. Null for base card listings.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parallel_name":{"description":"Parallel variant name. Null for base card listings.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["price","source"]},"MarketplaceRecordInput":{"type":"object","properties":{"title":{"type":"string","description":"Listing title"},"price":{"description":"Current price or starting bid in USD","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"source":{"type":"string","description":"Marketplace source"},"listing_type":{"description":"Type of listing","anyOf":[{"type":"string","enum":["auction","fixed","search"]},{"type":"null"}]},"url":{"description":"URL to the listing","anyOf":[{"type":"string"},{"type":"null"}]},"image_url":{"description":"Primary image URL","anyOf":[{"type":"string"},{"type":"null"}]},"condition":{"description":"Condition description from seller","anyOf":[{"type":"string"},{"type":"null"}]},"end_date":{"description":"Listing end date in ISO 8601 format","anyOf":[{"type":"string"},{"type":"null"}]},"bid_count":{"description":"Number of bids (auctions only)","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"parallel_id":{"description":"Parallel variant UUID. Null for base card listings.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parallel_name":{"description":"Parallel variant name. Null for base card listings.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title","source"]},"PricingCardContextInput":{"type":"object","properties":{"card_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Card UUID"},"name":{"type":"string","description":"Card name/subject"},"number":{"description":"Card number in set","anyOf":[{"type":"string"},{"type":"null"}]},"set":{"type":"object","properties":{"set_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Set UUID"},"name":{"type":"string","description":"Set name"},"year":{"type":"string","description":"Release year"},"release":{"type":"string","description":"Release name"}},"required":["set_id","name","year","release"],"description":"Set context"},"parallel":{"description":"Parallel context if filtered by parallel","anyOf":[{"type":"object","properties":{"parallel_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Parallel UUID"},"name":{"type":"string","description":"Parallel name"}},"required":["parallel_id","name"]},{"type":"null"}]}},"required":["card_id","name","set"]},"PricingQueryEchoInput":{"type":"object","properties":{"parallel_id":{"description":"Parallel UUID filter applied","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"grade_id":{"description":"Grade UUID filter applied","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"period":{"description":"Period filter applied (pricing only)","type":"string"},"listing_type":{"description":"Listing type filter applied","type":"string"},"as_of_date":{"type":"string","description":"Date the data was retrieved"}},"required":["as_of_date"]},"SourceBreakdownItemInput":{"type":"object","properties":{"source":{"type":"string","description":"Source name"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records from this source"}},"required":["source","count"]},"PricingMetaInput":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceBreakdownItemInput"},"description":"Breakdown by data source"},"last_sale_date":{"description":"Date of most recent sale","anyOf":[{"type":"string"},{"type":"null"}]},"total_records":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total records returned across all sections"}},"required":["sources","total_records"]},"RawPricingSectionInput":{"type":"object","properties":{"period_days":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Period in days that was applied"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records"},"records":{"type":"array","items":{"$ref":"#/components/schemas/PricingRecordInput"},"description":"Pricing records for ungraded cards"}},"required":["period_days","count","records"]},"PricingGradeGroupInput":{"type":"object","properties":{"grade_value":{"type":"string","description":"Grade value (e.g., \"10\", \"9.5\")"},"grade_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grade UUID"},"period_days":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Period in days that was applied"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records in this group"},"records":{"type":"array","items":{"$ref":"#/components/schemas/PricingRecordInput"},"description":"Pricing records for this grade"}},"required":["grade_value","grade_id","period_days","count","records"]},"PricingCompanyGroupInput":{"type":"object","properties":{"company_name":{"type":"string","description":"Grading company name (e.g., \"PSA\")"},"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grading company UUID"},"grades":{"type":"array","items":{"$ref":"#/components/schemas/PricingGradeGroupInput"},"description":"Grade groups for this company"}},"required":["company_name","company_id","grades"]},"PricingResponseInput":{"type":"object","properties":{"card":{"description":"Card context information","$ref":"#/components/schemas/PricingCardContextInput"},"query":{"description":"Echo of query parameters applied","$ref":"#/components/schemas/PricingQueryEchoInput"},"raw":{"description":"Ungraded/raw pricing data","$ref":"#/components/schemas/RawPricingSectionInput"},"graded":{"type":"array","items":{"$ref":"#/components/schemas/PricingCompanyGroupInput"},"description":"Graded pricing data grouped by company and grade"},"meta":{"description":"Response metadata","$ref":"#/components/schemas/PricingMetaInput"}},"required":["card","query","raw","graded","meta"]},"RawMarketplaceSectionInput":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of active listings"},"records":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceRecordInput"},"description":"Active marketplace listings"}},"required":["count","records"]},"MarketplaceGradeGroupInput":{"type":"object","properties":{"grade_value":{"type":"string","description":"Grade value"},"grade_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grade UUID"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of listings"},"records":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceRecordInput"},"description":"Active listings for this grade"}},"required":["grade_value","grade_id","count","records"]},"MarketplaceCompanyGroupInput":{"type":"object","properties":{"company_name":{"type":"string","description":"Grading company name"},"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grading company UUID"},"grades":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceGradeGroupInput"},"description":"Grade groups"}},"required":["company_name","company_id","grades"]},"MarketplaceMetaInput":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceBreakdownItemInput"},"description":"Breakdown by data source"},"total_records":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total records returned"}},"required":["sources","total_records"]},"MarketplaceResponseInput":{"type":"object","properties":{"card":{"description":"Card context information","$ref":"#/components/schemas/PricingCardContextInput"},"query":{"description":"Echo of query parameters applied","$ref":"#/components/schemas/PricingQueryEchoInput"},"raw":{"description":"Ungraded active listings","$ref":"#/components/schemas/RawMarketplaceSectionInput"},"graded":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceCompanyGroupInput"},"description":"Graded active listings grouped by company and grade"},"meta":{"description":"Response metadata","$ref":"#/components/schemas/MarketplaceMetaInput"}},"required":["card","query","raw","graded","meta"]},"BulkPricingResultInput":{"type":"object","properties":{"card_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Card UUID"},"success":{"type":"boolean","description":"Whether pricing was successfully retrieved"},"data":{"description":"Pricing data when successful","$ref":"#/components/schemas/PricingResponseInput"},"error":{"description":"Error details when unsuccessful","type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"}},"required":["code","message"]}},"required":["card_id","success"]},"BulkPricingResponseInput":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkPricingResultInput"},"description":"Pricing results for each requested card"},"meta":{"type":"object","properties":{"requested":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards requested"},"successful":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards with successful results"},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards that failed"}},"required":["requested","successful","failed"],"description":"Summary counts"}},"required":["results","meta"]},"ReleaseCalendarEntryInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the release calendar entry"},"name":{"type":"string","description":"Name of the release"},"year":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release year"},"release_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Expected or actual release date (YYYY-MM-DD)"},"pre_order_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Date when pre-orders open (YYYY-MM-DD)"},"segment_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Unique identifier of the associated market segment"},"manufacturer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Unique identifier of the associated manufacturer"}},"required":["id","name","year","release_date","pre_order_date","segment_id","manufacturer_id"]},"PaginatedReleaseCalendarResponseInput":{"type":"object","properties":{"release_calendar":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseCalendarEntryInput"},"description":"List of release calendar entries"},"total_count":{"type":"number","description":"Total number of entries matching the query"},"skip":{"type":"number","description":"Number of items skipped (offset)"},"take":{"type":"number","description":"Number of items included in this page"}},"required":["release_calendar","total_count","skip","take"]},"BasicHealthResponseInput":{"type":"object","properties":{"status":{"type":"string","description":"Overall health status of the API (e.g., \"healthy\")"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when the health check was performed"}},"required":["status","timestamp"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code for programmatic handling"}},"required":["error","code"],"additionalProperties":false},"BatchOperationError":{"type":"object","properties":{"index":{"type":"number","description":"Index of the failed item in the request array"},"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Card UUID that failed to process"},"error":{"type":"string","description":"Error message describing why the operation failed"}},"required":["index","cardId","error"],"additionalProperties":false},"ServerMessage":{"type":"object","properties":{"type":{"type":"string","enum":["info","warning"],"description":"Message severity level"},"message":{"type":"string","description":"Human-readable message text"}},"required":["type","message"],"additionalProperties":false},"CreateList":{"type":"object","properties":{"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the collector who will own this list"},"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}},"required":["collectorId"],"additionalProperties":false},"UpdateList":{"type":"object","properties":{"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}},"additionalProperties":false},"ListCardItem":{"type":"object","properties":{"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the card to add to the list"}},"required":["cardId"],"additionalProperties":false},"AddCardToList":{"anyOf":[{"$ref":"#/components/schemas/ListCardItem"},{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/ListCardItem"},"description":"Batch of cards to add (max 100)"}]},"List":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the list"},"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the collector who owns this list"},"name":{"description":"Name of the list","type":"string"},"description":{"description":"Description of the list","type":"string"}},"required":["id","collectorId"],"additionalProperties":false},"ListCard":{"type":"object","properties":{"id":{"type":"string","description":"Internal ID for the list card"},"listId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the list"},"cardId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the card"}},"required":["id","listId","cardId"],"additionalProperties":false},"PaginatedListsResponse":{"type":"object","properties":{"lists":{"type":"array","items":{"$ref":"#/components/schemas/List"},"description":"Array of list entities (want lists, collection goals, etc.)"},"total_count":{"type":"number","description":"Total number of lists matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["lists","total_count","skip","take"],"additionalProperties":false},"PaginatedListCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ListCard"},"description":"Array of cards in this list with minimal metadata"},"total_count":{"type":"number","description":"Total number of cards in this list"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["cards","total_count","skip","take"],"additionalProperties":false},"BatchListCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ListCard"},"description":"Successfully created cards"},"errors":{"description":"Any errors that occurred during batch creation","type":"array","items":{"$ref":"#/components/schemas/BatchOperationError"}}},"required":["cards"],"additionalProperties":false},"AddCardsToListResponse":{"anyOf":[{"$ref":"#/components/schemas/ListCard"},{"$ref":"#/components/schemas/BatchListCardsResponse"}]},"CreateCollector":{"type":"object","properties":{"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}},"additionalProperties":false},"UpdateCollector":{"type":"object","properties":{"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}},"additionalProperties":false},"Collector":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the collector"},"name":{"description":"Name of the collector (e.g., \"Mike\", \"Eric\")","type":"string"}},"required":["id"],"additionalProperties":false},"PaginatedCollectorsResponse":{"type":"object","properties":{"collectors":{"type":"array","items":{"$ref":"#/components/schemas/Collector"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["collectors","total_count","skip","take"],"additionalProperties":false},"CreateCollection":{"type":"object","properties":{"collectorId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the collector who will own this collection"},"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}},"required":["collectorId"],"additionalProperties":false},"UpdateCollection":{"type":"object","properties":{"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}},"additionalProperties":false},"CollectionCardItem":{"type":"object","properties":{"cardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the card to add to the collection"},"parallelId":{"description":"UUID of the card parallel if applicable","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"gradeId":{"description":"UUID of the grade if card is graded","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quantity":{"default":1,"description":"Quantity of this card to add","type":"number","minimum":1},"buyPrice":{"description":"Purchase price (numeric string with up to 2 decimal places)","type":"string"},"buyDate":{"description":"Purchase date in YYYY-MM-DD format","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"sellPrice":{"description":"Listed selling price (numeric string with up to 2 decimal places)","type":"string"},"soldPrice":{"description":"Actual sold price (numeric string with up to 2 decimal places)","type":"string"},"soldDate":{"description":"Sale date in YYYY-MM-DD format","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["cardId","quantity"],"additionalProperties":false},"CreateCollectionCard":{"anyOf":[{"$ref":"#/components/schemas/CollectionCardItem"},{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/CollectionCardItem"},"description":"Batch of cards to add (max 100)"}]},"UpdateCollectionCard":{"type":"object","properties":{"parallelId":{"description":"UUID of the card parallel (null to remove)","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"gradeId":{"description":"UUID of the grade (null to remove)","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"quantity":{"description":"Updated quantity","type":"number","minimum":1},"buyPrice":{"description":"Purchase price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"buyDate":{"description":"Purchase date (null to remove)","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"sellPrice":{"description":"Listed selling price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"soldPrice":{"description":"Actual sold price (null to remove)","anyOf":[{"type":"string"},{"type":"null"}]},"soldDate":{"description":"Sale date (null to remove)","anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]}},"additionalProperties":false},"Collection":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the collection"},"collectorId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"ID of the collector who owns this collection"},"name":{"description":"Name of the collection","type":"string"},"description":{"description":"Description of the collection","type":"string"}},"required":["id","collectorId"],"additionalProperties":false},"CollectionCard":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the collection card"},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection this card belongs to"},"cardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the card"},"parallelId":{"description":"ID of the card parallel if applicable","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"gradeId":{"description":"UUID of the grade if card is graded","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quantity":{"default":1,"description":"Quantity of this card in the collection","type":"number","minimum":1},"buyPrice":{"description":"Purchase price of the card","type":"string"},"buyDate":{"description":"Date the card was purchased (YYYY-MM-DD)","type":"string"},"sellPrice":{"description":"Listed selling price of the card","type":"string"},"soldPrice":{"description":"Actual sold price of the card","type":"string"},"soldDate":{"description":"Date the card was sold (YYYY-MM-DD)","type":"string"}},"required":["id","collectionId","cardId","quantity"],"additionalProperties":false},"PaginatedCollectionsResponse":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["collections","total_count","skip","take"],"additionalProperties":false},"PaginatedCollectionCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CollectionCard"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["cards","total_count","skip","take"],"additionalProperties":false},"BatchCollectionCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CollectionCard"},"description":"Successfully created cards"},"errors":{"description":"Any errors that occurred during batch creation","type":"array","items":{"$ref":"#/components/schemas/BatchOperationError"}}},"required":["cards"],"additionalProperties":false},"AddCollectionCardsResponse":{"anyOf":[{"$ref":"#/components/schemas/CollectionCard"},{"$ref":"#/components/schemas/BatchCollectionCardsResponse"}]},"TopCardInGroup":{"type":"object","properties":{"cardId":{"type":"string","description":"Card UUID"},"cardName":{"type":"string","description":"Card name"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"buyPrice":{"description":"Purchase price per card","type":"string"},"quantity":{"type":"number","description":"Quantity in collection"}},"required":["cardId","cardName","setName","releaseName","releaseYear","quantity"],"additionalProperties":false},"CollectionBreakdownSummary":{"type":"object","properties":{"totalGroups":{"type":"number","description":"Total number of groups"},"totalCards":{"type":"number","description":"Total number of cards in collection"},"totalQuantity":{"type":"number","description":"Total quantity including duplicates"},"totalInvested":{"description":"Total amount invested (sum of buy prices)","type":"string"},"groupedBy":{"type":"string","description":"The dimension used for grouping"}},"required":["totalGroups","totalCards","totalQuantity","groupedBy"],"additionalProperties":false},"BreakdownPagination":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of groups"},"skip":{"type":"number","description":"Number of groups skipped"},"take":{"type":"number","description":"Number of groups included"},"page":{"type":"number","description":"Current page number"},"pages":{"type":"number","description":"Total number of pages"}},"required":["total_count","skip","take","page","pages"],"additionalProperties":false},"BreakdownGroup":{"type":"object","properties":{"groupKey":{"type":"string","description":"The grouping key (e.g., set name, year, grade)"},"groupId":{"description":"The UUID of the group entity if applicable","type":"string"},"cardCount":{"type":"number","description":"Number of cards in this group"},"uniqueCardCount":{"type":"number","description":"Number of unique cards (ignoring duplicates)"},"totalQuantity":{"type":"number","description":"Total quantity including duplicates"},"totalBuyPrice":{"description":"Total purchase price for cards in group","type":"string"},"totalSoldPrice":{"description":"Total sold price for sold cards","type":"string"},"averageBuyPrice":{"description":"Average purchase price per card","type":"string"},"percentageOfCollection":{"type":"number","description":"Percentage this group represents of total collection"},"topCards":{"description":"Top cards in this group","type":"array","items":{"$ref":"#/components/schemas/TopCardInGroup"}}},"required":["groupKey","cardCount","uniqueCardCount","totalQuantity","percentageOfCollection"],"additionalProperties":false},"CollectionBreakdownResponse":{"type":"object","properties":{"summary":{"description":"Aggregate statistics across all groups","$ref":"#/components/schemas/CollectionBreakdownSummary"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownGroup"},"description":"Array of breakdown groups"},"pagination":{"description":"Pagination metadata","$ref":"#/components/schemas/BreakdownPagination"}},"required":["summary","groups","pagination"],"additionalProperties":false},"SetProgress":{"type":"object","properties":{"setId":{"type":"string","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"totalCards":{"type":"number","description":"Total number of cards in set"},"ownedCards":{"type":"number","description":"Number of unique cards owned"},"missingCards":{"type":"array","items":{"type":"string"},"description":"Array of missing card UUIDs"},"completionPercentage":{"type":"number","description":"Percentage complete (0-100)"},"difficultyScore":{"description":"Difficulty score based on card availability (0-100)","type":"number"}},"required":["setId","setName","releaseName","releaseYear","totalCards","ownedCards","missingCards","completionPercentage"],"additionalProperties":false},"SetProgressSummary":{"type":"object","properties":{"totalSets":{"type":"number","description":"Total number of sets represented in collection"},"nearCompleteSets":{"type":"number","description":"Number of sets >80% complete"},"fullyCompleteSets":{"type":"number","description":"Number of fully complete sets"}},"required":["totalSets","nearCompleteSets","fullyCompleteSets"],"additionalProperties":false},"SetProgressListResponse":{"type":"object","properties":{"summary":{"description":"Aggregate statistics across all sets","$ref":"#/components/schemas/SetProgressSummary"},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetProgress"},"description":"Array of set progress entries"},"total_count":{"type":"number","description":"Total number of sets matching filters"},"skip":{"type":"number","description":"Number of records skipped"},"take":{"type":"number","description":"Number of records returned"}},"required":["summary","sets","total_count","skip","take"],"additionalProperties":false},"ParallelSetProgress":{"type":"object","properties":{"setId":{"type":"string","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"parallelId":{"type":"string","description":"Parallel UUID"},"parallelName":{"type":"string","description":"Parallel name (e.g., Refractor, Gold)"},"totalCards":{"type":"number","description":"Total number of cards in set"},"ownedCards":{"type":"number","description":"Number of this parallel owned"},"missingCards":{"type":"array","items":{"type":"string"},"description":"Array of missing card UUIDs for this parallel"},"completionPercentage":{"type":"number","description":"Percentage complete for this parallel (0-100)"}},"required":["setId","setName","releaseName","releaseYear","parallelId","parallelName","totalCards","ownedCards","missingCards","completionPercentage"],"additionalProperties":false},"CollectionOverview":{"type":"object","properties":{"totalCards":{"type":"number","description":"Total number of card entries in collection"},"uniqueCards":{"type":"number","description":"Number of unique cards (ignoring duplicates)"},"totalQuantity":{"type":"number","description":"Total quantity including all duplicates"}},"required":["totalCards","uniqueCards","totalQuantity"],"additionalProperties":false},"CollectionFinancials":{"type":"object","properties":{"totalInvested":{"description":"Total amount invested (sum of buy prices)","type":"string"},"totalRealizedGains":{"description":"Total gains from sold cards (soldPrice - buyPrice)","type":"string"}},"additionalProperties":false},"CollectionComposition":{"type":"object","properties":{"gradedCount":{"type":"number","description":"Number of graded cards"},"rawCount":{"type":"number","description":"Number of raw (ungraded) cards"},"gradedPercentage":{"type":"number","description":"Percentage of collection that is graded"},"forSaleCount":{"type":"number","description":"Number of cards listed for sale"},"soldCount":{"type":"number","description":"Number of cards that have been sold"}},"required":["gradedCount","rawCount","gradedPercentage","forSaleCount","soldCount"],"additionalProperties":false},"CollectionAnalyticsResponse":{"type":"object","properties":{"overview":{"description":"Collection overview with basic counts","$ref":"#/components/schemas/CollectionOverview"},"financials":{"description":"Investment and return metrics based on user-entered buy/sell data","$ref":"#/components/schemas/CollectionFinancials"},"composition":{"description":"Breakdown of collection by type and status","$ref":"#/components/schemas/CollectionComposition"}},"required":["overview","financials","composition"],"additionalProperties":false},"UploadCollectionCardImageResponse":{"type":"object","properties":{"imageId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the image record"},"uploadedAt":{"type":"string","description":"Timestamp when the image was uploaded"},"fullImageUrl":{"type":"string","description":"URL to retrieve the full-resolution image"},"thumbnailUrl":{"type":"string","description":"URL to retrieve the thumbnail image"}},"required":["imageId","uploadedAt","fullImageUrl","thumbnailUrl"],"additionalProperties":false},"CreateBinder":{"type":"object","properties":{"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}},"additionalProperties":false},"UpdateBinder":{"type":"object","properties":{"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}},"additionalProperties":false},"AddCardToBinder":{"type":"object","properties":{"collectionCardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"UUID of the collection card to add to the binder"}},"required":["collectionCardId"],"additionalProperties":false},"Binder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the binder"},"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection this binder belongs to"},"name":{"description":"Name of the binder","type":"string"},"description":{"description":"Description of the binder","type":"string"}},"required":["id","collectionId"],"additionalProperties":false},"BinderCard":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the binder card link"},"binderId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the binder"},"collectionCardId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the collection card"}},"required":["id","binderId","collectionCardId"],"additionalProperties":false},"PaginatedBindersResponse":{"type":"object","properties":{"binders":{"type":"array","items":{"$ref":"#/components/schemas/Binder"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["binders","total_count","skip","take"],"additionalProperties":false},"PaginatedBinderCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/BinderCard"}},"total_count":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}},"required":["cards","total_count","skip","take"],"additionalProperties":false},"FeedbackInput":{"type":"object","properties":{"feedback_type":{"description":"Category of feedback. Accepted values: data_error (incorrect data), missing_data (something is missing from the catalog), suggestion (improvement idea), bug (something is broken), other (does not fit other categories)","type":"string","enum":["data_error","missing_data","suggestion","bug","other"]},"message":{"type":"string","minLength":1,"maxLength":1000,"description":"Detailed description of the feedback. Include specifics such as what is wrong, what you expected, or what you suggest. Max 1000 characters."}},"required":["message"],"additionalProperties":false},"FeedbackResponse":{"type":"object","properties":{"unique_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for this feedback submission"},"entity_type":{"type":"string","enum":["release","set","card","product","manufacturer","segment","general","identify"],"description":"The type of entity this feedback is about"},"entity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The unique ID of the entity, or null for general feedback"},"feedback_type":{"anyOf":[{"type":"string","enum":["data_error","missing_data","suggestion","bug","other"],"description":"FeedbackType"},{"type":"null"}],"description":"The category of feedback submitted"},"message":{"type":"string","description":"The feedback message"},"status":{"type":"string","enum":["not_reviewed","under_review","fixed","wont_fix","duplicate","need_info"],"description":"Current review status of the feedback"},"created_at":{"type":"string","description":"ISO 8601 timestamp when the feedback was submitted"},"updated_at":{"type":"string","description":"ISO 8601 timestamp when the feedback was last updated"}},"required":["unique_id","entity_type","entity_id","feedback_type","message","status","created_at","updated_at"],"additionalProperties":false},"FeedbackSubmitResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/FeedbackResponse"}},"required":["success","message","data"],"additionalProperties":false},"FileUpload":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"The image file to analyze"}},"required":["image"],"additionalProperties":false},"FieldValue":{"type":"object","properties":{"key":{"type":"string","description":"Field key (e.g., \"HP\", \"Rarity\", \"Artist\")"},"value":{"type":"string","description":"Field value for the given key"}},"required":["key","value"],"additionalProperties":false},"FieldValues":{"type":"array","items":{"$ref":"#/components/schemas/FieldValue"}},"CardSuggestion":{"type":"object","properties":{"id":{"description":"UUID of the suggested card","type":"string"},"setName":{"description":"Set name for the suggested card","type":"string"},"fields":{"description":"Key-value field properties for the suggested card. Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValues"}},"additionalProperties":false},"CardDetails":{"type":"object","properties":{"id":{"description":"UUID of the identified card. Present only for exact card matches.","type":"string"},"segmentId":{"description":"UUID of the segment. Present for both exact card and set-level matches.","type":"string"},"releaseId":{"description":"UUID of the release. Present for both exact card and set-level matches.","type":"string"},"setId":{"description":"UUID of the set. Present for both exact card and set-level matches.","type":"string"},"year":{"description":"Release year from catalog (e.g., \"2023\", \"1989\")","type":"string"},"manufacturer":{"description":"Card manufacturer from catalog (e.g., \"Topps\", \"Panini\", \"Upper Deck\")","type":"string"},"releaseName":{"description":"Release/product name from catalog (e.g., \"Topps Chrome\", \"Prizm Basketball\")","type":"string"},"setName":{"description":"Set name from catalog (e.g., \"Base Set\", \"Rookie Variations\")","type":"string"},"name":{"description":"Player or subject name. Present only for exact card matches.","type":"string"},"number":{"description":"Card number. Present only for exact card matches.","type":"string"},"description":{"description":"Descriptive text for the card when available. Omitted if no description exists.","type":"string"},"numberedTo":{"description":"Print run for numbered cards (e.g., 25 for a /25 card). Omitted if the card is not numbered.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attributes":{"description":"Notable attributes of the card (e.g., [\"Rookie\", \"Autograph\"]). Omitted if the card has no attributes.","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the parent card when this card is a variation. Omitted if the card is not a variation.","type":"string"},"parallel":{"description":"Parallel variant info. Present only for exact card matches with an identified parallel.","$ref":"#/components/schemas/ParallelSummary"},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValues"},"suggestions":{"description":"Alternative card matches when multiple reprints score similarly. Omitted when there are no suggestions.","type":"array","items":{"$ref":"#/components/schemas/CardSuggestion"}}},"additionalProperties":false},"IdentificationData":{"type":"object","properties":{"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"AI confidence level for this detection (High: 90-100%, Medium: 75-89%, Low: 50-74%)"},"card":{"description":"Identified card details. Completeness reflects match level: full fields for exact card match, set-level fields for set match, empty object for unmatched detection.","$ref":"#/components/schemas/CardDetails"},"grading":{"description":"Grading slab data matched to this specific card detection. Present when the card is inside a graded slab.","$ref":"#/components/schemas/SlabGradingDetail"}},"required":["confidence","card"],"additionalProperties":false},"IdentifyCardResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the identification process completed successfully"},"requestId":{"type":"string","description":"Unique identifier for tracking this identification request"},"detections":{"description":"Array of card detections from the image. Multiple cards may be detected in a single image. Each detection may include grading data if the card is inside a graded slab. Empty if no cards found.","type":"array","items":{"$ref":"#/components/schemas/IdentificationData"}},"processingTime":{"description":"Total processing time in milliseconds for AI analysis and catalog matching","type":"number"},"messages":{"description":"Server advisory messages (e.g., image quality warnings)","type":"array","items":{"$ref":"#/components/schemas/ServerMessage"}}},"required":["success","requestId"],"additionalProperties":false},"DetectCardResponse":{"type":"object","properties":{"detected":{"type":"boolean","description":"Whether one or more trading cards were detected in the image"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of trading cards detected in the image"},"requestId":{"type":"string","description":"Unique identifier for tracking this detection request"},"processingTime":{"type":"number","description":"Total processing time in milliseconds"},"messages":{"description":"Server advisory messages (e.g., image quality warnings)","type":"array","items":{"$ref":"#/components/schemas/ServerMessage"}}},"required":["detected","count","requestId","processingTime"],"additionalProperties":false},"SlabCompany":{"type":"object","properties":{"id":{"description":"UUID of the grading company from the catalog. Absent if company could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","description":"Grading company name detected on the slab (e.g., \"PSA\", \"BGS\", \"CGC\", \"SGC\")"}},"required":["name"],"additionalProperties":false},"SlabGrade":{"type":"object","properties":{"id":{"description":"UUID of the grade from the catalog. Absent if grade could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"value":{"description":"Grade value detected on the slab label","type":"string"},"condition":{"description":"Grade condition detected on the slab label","type":"string"}},"additionalProperties":false},"SlabQualifier":{"type":"object","properties":{"id":{"description":"UUID of the qualifier from the catalog. Absent if qualifier could not be matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"code":{"type":"string","description":"Qualifier code (e.g., OC, MC, PD, ST)"}},"required":["code"],"additionalProperties":false},"SlabAutoGrade":{"type":"object","properties":{"id":{"description":"UUID of the autograph grade from the catalog. Absent if not matched.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"value":{"description":"Autograph grade value","type":"string"},"condition":{"description":"Autograph grade condition","type":"string"}},"additionalProperties":false},"SlabGradingDetail":{"type":"object","properties":{"confidence":{"type":"string","enum":["High","Medium","Low"],"description":"Detection confidence level for this slab (High: 90-100%, Medium: 75-89%, Low: 50-74%)"},"company":{"description":"Grading company that issued this slab","$ref":"#/components/schemas/SlabCompany"},"grade":{"description":"Grade detected on the slab label","$ref":"#/components/schemas/SlabGrade"},"qualifier":{"description":"Defect qualifier detected on the slab label","$ref":"#/components/schemas/SlabQualifier"},"autoGrade":{"description":"Autograph grade detected on the slab label","$ref":"#/components/schemas/SlabAutoGrade"}},"required":["confidence","company"],"additionalProperties":false},"AIQueryRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language query"},"context":{"description":"Optional context for the query","$ref":"#/components/schemas/AIContext"},"conversationHistory":{"description":"Optional conversation history (max 50 messages). Messages should alternate between user and assistant roles.","maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}},"maxIterations":{"description":"Maximum tool use iterations (default: 5)","type":"integer","minimum":1,"maximum":10}},"required":["query"],"additionalProperties":false},"AIContext":{"type":"object","properties":{"collectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"userId":{"type":"string"}},"additionalProperties":{}},"ConversationMessage":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"The role of the message sender"},"content":{"type":"string","minLength":1,"maxLength":10000,"description":"The message content"}},"required":["role","content"],"additionalProperties":false},"AIQueryResponse":{"type":"object","properties":{"answer":{"type":"string","description":"AI-generated response to the query"},"toolsUsed":{"description":"List of MCP tools used to answer the query","type":"array","items":{"type":"string"}},"processingTime":{"type":"number","description":"Time taken to process the query in milliseconds"}},"required":["answer","processingTime"],"additionalProperties":false},"AIError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error","code"],"additionalProperties":false},"ApiKeyUsage":{"type":"object","properties":{"key":{"type":"string","description":"The API key (masked or full depending on context)"},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total number of API calls made using this key for the current billing period"}},"required":["key","calls"],"additionalProperties":false},"SubscriptionInfo":{"type":"object","properties":{"calls":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total aggregate number of API calls made across all API keys for the current billing period"},"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyUsage"},"description":"Array containing usage information for the current API key only"}},"required":["calls","api_keys"],"additionalProperties":false},"ImageJsonResponse":{"type":"object","properties":{"data":{"type":"string","description":"Base64 data URI (ready for use in HTML img src)"},"contentType":{"type":"string","description":"MIME type of the image"},"size":{"description":"Size of the image in bytes","type":"number"}},"required":["data","contentType"],"additionalProperties":false},"Segment":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the segment. Format: UUID v4. This ID is permanent and used for all API operations involving this segment."},"name":{"type":"string","description":"Display name of the segment. Examples: \"Sports\", \"Entertainment\", \"Gaming\". Used for categorizing releases and filtering."},"is_identifiable":{"type":"boolean","description":"Whether cards in this segment can be identified by the CardSightAI identification service."}},"required":["id","name","is_identifiable"],"additionalProperties":false},"Manufacturer":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the manufacturer. Format: UUID v4. This ID is permanent and used for all API operations involving this manufacturer."},"name":{"type":"string","description":"Official name of the manufacturer. Examples: \"Topps\", \"Panini America\", \"Upper Deck\". This is the primary display name."},"description":{"description":"Additional information about the manufacturer, such as founding year, headquarters, or notable product lines. May be null if not provided.","type":"string"}},"required":["id","name"],"additionalProperties":false},"Release":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable"],"additionalProperties":false},"Set":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this set belongs to. Links to the release entity. A release typically contains multiple sets."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."}},"required":["id","releaseId","name","is_identifiable"],"additionalProperties":false},"Card":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"}},"required":["releaseId","setId","id","name"],"additionalProperties":false},"Parallel":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this parallel belongs to. Links to the set entity. Each set can have multiple parallel types."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true}},"required":["id","setId","name"],"additionalProperties":false},"Attribute":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"}},"required":["id","name","shortName"],"additionalProperties":false},"Field":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"}},"required":["id","key","name"],"additionalProperties":false},"ParallelSummary":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"},"cards":{"description":"Card UUIDs that have this parallel. Only present when isPartial is true.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}}},"required":["id","name"],"additionalProperties":false},"AttributeSummary":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"},"cardCount":{"type":"number","description":"Number of cards with this attribute"}},"required":["id","name","shortName","cardCount"],"additionalProperties":false},"FieldSummary":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"},"usageCount":{"type":"number","description":"Total number of catalog entities (cards, sets, releases, and segments) that have a value for this field."}},"required":["id","key","name","usageCount"],"additionalProperties":false},"ReleaseSummary":{"type":"object","properties":{"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"description":{"type":"string"}},"required":["manufacturerId","segmentId","id","year","name","is_identifiable"],"additionalProperties":false},"SetSummaryWithCounts":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"}},"required":["id","name","is_identifiable","cardCount","parallelCount"],"additionalProperties":false},"CardSummary":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"setName":{"type":"string","description":"Name of the set this card belongs to"},"releaseName":{"description":"Name of the release","type":"string"},"releaseYear":{"description":"Year of the release","type":"string"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallels":{"description":"Simplified list of parallel variants for this card. Includes id, name, and numberedTo.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"}},"required":["id","name"],"additionalProperties":false}},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValues"}},"required":["releaseId","setId","id","name","setName"],"additionalProperties":false},"DetailedCard":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"setName":{"type":"string","description":"Name of the set"},"numberedTo":{"description":"Limited print run number for this specific card","type":"number"},"parallelCount":{"type":"number","description":"Number of parallel variants for this card"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummary"},"description":"List of parallel variants available for this card"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"fields":{"description":"Key-value field properties inherited from segment, release, set, and card levels (e.g., HP, Rarity, Artist). Additive — duplicate keys across levels are preserved. Omitted when no fields apply anywhere in the lineage.","$ref":"#/components/schemas/FieldValues"}},"required":["releaseId","setId","id","name","setName","parallelCount","parallels"],"additionalProperties":false},"ReleaseWithSets":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetSummaryWithCounts"},"description":"Sets within this release"},"fields":{"description":"Key-value field properties inherited from segment and release levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValues"}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable","sets"],"additionalProperties":false},"ParallelWithSet":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"description":{"description":"Additional details about the parallel such as print run, special features, or visual description. May be null.","type":"string"},"isPartial":{"description":"Present and true only if this parallel applies to specific cards (e.g., cards 1-400 of a 800-card set). Omitted if parallel applies to the entire set.","type":"boolean","const":true},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"},"cards":{"description":"Card UUIDs that have this parallel. Only present when isPartial is true.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Set UUID"},"setName":{"type":"string","description":"Set name"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"},"cardCount":{"type":"number","description":"Number of base cards in the set"}},"required":["id","name","setId","setName","releaseId","releaseName","releaseYear","cardCount"],"additionalProperties":false},"PaginatedSegmentsResponse":{"type":"object","properties":{"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Array of market segment entities (e.g., Sports, Entertainment, Gaming)"},"total_count":{"type":"number","description":"Total number of segments matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["segments","total_count","skip","take"],"additionalProperties":false},"PaginatedManufacturersResponse":{"type":"object","properties":{"manufacturers":{"type":"array","items":{"$ref":"#/components/schemas/Manufacturer"},"description":"Array of card manufacturer entities (e.g., Topps, Panini, Upper Deck)"},"total_count":{"type":"number","description":"Total number of manufacturers matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["manufacturers","total_count","skip","take"],"additionalProperties":false},"PaginatedReleasesResponse":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"},"description":"Array of release entities with summary information (e.g., \"2023 Topps Chrome Baseball\")"},"total_count":{"type":"number","description":"Total number of releases matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["releases","total_count","skip","take"],"additionalProperties":false},"DetailedReleaseResponse":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the release. Format: UUID v4. This ID is permanent and used for all API operations involving this release."},"segmentId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the segment this release belongs to. Links to the segment entity. Determines the market category (Sports, Entertainment, etc.)."},"manufacturerId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the manufacturer that produced this release. Links to the manufacturer entity."},"year":{"type":"string","description":"Year the release was issued. Format: YYYY (e.g., \"2023\"). Used for chronological filtering and sorting."},"name":{"type":"string","description":"Full name of the release. Typically includes year, brand, and sport/category. Example: \"2023 Topps Chrome Baseball\""},"description":{"description":"Additional details about the release, such as special features, number of cards, or notable inclusions. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether any set in this release can be identified by the CardSightAI identification service. True if at least one set has is_identifiable = true."},"sets":{"type":"array","items":{"$ref":"#/components/schemas/SetSummaryWithCounts"},"description":"Sets within this release"},"fields":{"description":"Key-value field properties inherited from segment and release levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValues"}},"required":["id","segmentId","manufacturerId","year","name","is_identifiable","sets"],"additionalProperties":false},"PaginatedCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardSummary"},"description":"Array of card entities with summary information"},"total_count":{"type":"number","description":"Total number of cards matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["cards","total_count","skip","take"],"additionalProperties":false},"PaginatedSetsResponse":{"type":"object","properties":{"sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"}},"required":["id","name","is_identifiable","cardCount","parallelCount","releaseId","releaseName","releaseYear"],"additionalProperties":false},"description":"Array of set entities with card counts and release information"},"total_count":{"type":"number","description":"Total number of sets matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["sets","total_count","skip","take"],"additionalProperties":false},"DetailedSetResponse":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this set belongs to. Links to the release entity. A release typically contains multiple sets."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"cardCount":{"type":"number","description":"Number of base cards"},"parallelCount":{"type":"number","description":"Number of parallel types"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummary"},"description":"List of parallel variants in this set"},"fields":{"description":"Key-value field properties inherited from segment, release, and set levels. Additive — duplicate keys across levels are preserved. Omitted when no fields apply.","$ref":"#/components/schemas/FieldValues"}},"required":["id","releaseId","name","is_identifiable","releaseName","releaseYear","cardCount","parallelCount","parallels"],"additionalProperties":false},"DetailedCardResponse":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"releaseName":{"type":"string","description":"Name of the release"},"releaseYear":{"type":"string","description":"Year of the release"},"setName":{"type":"string","description":"Name of the set"},"numberedTo":{"description":"Limited print run number for this specific card","type":"number"},"parallelCount":{"type":"number","description":"Number of parallel variants for this card"},"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelSummary"},"description":"List of parallel variants available for this card"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"fields":{"description":"Key-value field properties inherited from segment, release, set, and card levels (e.g., HP, Rarity, Artist). Additive — duplicate keys across levels are preserved. Omitted when no fields apply anywhere in the lineage.","$ref":"#/components/schemas/FieldValues"}},"required":["releaseId","setId","id","name","setName","parallelCount","parallels"],"additionalProperties":false},"PaginatedAttributesResponse":{"type":"object","properties":{"attributes":{"type":"array","items":{"$ref":"#/components/schemas/DetailedAttributeResponse"},"description":"Array of card attribute entities (e.g., Rookie Card, Autograph, Memorabilia)"},"total_count":{"type":"number","description":"Total number of attributes matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["attributes","total_count","skip","take"],"additionalProperties":false},"DetailedAttributeResponse":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the attribute. Format: UUID v4. This ID is permanent and used for all API operations involving this attribute."},"name":{"type":"string","description":"Full descriptive name of the attribute. Examples: \"Rookie Card\", \"Autograph\", \"Game-Used Memorabilia\". Used for display purposes."},"shortName":{"type":"string","description":"Abbreviated code for the attribute. Examples: \"RC\" (Rookie Card), \"AU\" (Autograph), \"GU\" (Game-Used). Used for compact display and filtering."},"description":{"description":"Detailed explanation of what this attribute represents, when it applies, or any special notes. May be null.","type":"string"},"cardCount":{"type":"number","description":"Number of cards with this attribute"}},"required":["id","name","shortName","cardCount"],"additionalProperties":false},"PaginatedFieldsResponse":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/DetailedFieldResponse"},"description":"Array of field definitions with total usage counts across cards, sets, releases, and segments"},"total_count":{"type":"number","description":"Total number of fields matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["fields","total_count","skip","take"],"additionalProperties":false},"DetailedFieldResponse":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the field. Format: UUID v4. This ID is permanent and used for all API operations involving this field."},"key":{"type":"string","description":"Field key/code used when referencing this field in values and filters. Examples: \"HP\", \"RARITY\", \"ARTIST\". Typically uppercase."},"name":{"type":"string","description":"Display name of the field. Examples: \"Hit Points\", \"Rarity\", \"Artist\". Used for display purposes."},"description":{"description":"Detailed explanation of what this field represents. Omitted when not provided.","type":"string"},"usageCount":{"type":"number","description":"Total number of catalog entities (cards, sets, releases, and segments) that have a value for this field."}},"required":["id","key","name","usageCount"],"additionalProperties":false},"PaginatedParallelsResponse":{"type":"object","properties":{"parallels":{"type":"array","items":{"$ref":"#/components/schemas/ParallelWithSet"},"description":"Array of parallel variants with associated set information (e.g., Refractor, Prizm, numbered parallels)"},"total_count":{"type":"number","description":"Total number of parallels matching the query filters"},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination"},"take":{"type":"number","description":"Number of results included in this page"}},"required":["parallels","total_count","skip","take"],"additionalProperties":false},"DetailedParallelResponse":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\"."},"description":{"description":"Additional details about the parallel such as special features or visual description. May be null.","type":"string"},"numberedTo":{"description":"Limited print run number. Example: 50 means /50 parallel. Null for unlimited parallels.","type":"number"},"isPartial":{"type":"boolean","description":"True if this parallel applies to specific cards only (e.g., cards 1-400 of a 800-card set). False if it applies to the entire set."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this parallel belongs to."},"setName":{"type":"string","description":"Name of the set this parallel belongs to."},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release containing this parallel's set."},"releaseName":{"type":"string","description":"Name of the release (e.g., \"2023 Topps Chrome Baseball\")."},"releaseYear":{"type":"string","description":"Year the release was issued (e.g., \"2023\")."},"cards":{"description":"Array of card UUIDs that have this parallel variant. Only present when isPartial=true. Empty array if partial but no cards mapped.","type":"array","items":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID"}}},"required":["id","name","isPartial","setId","setName","releaseId","releaseName","releaseYear"],"additionalProperties":false},"CatalogSegmentBreakdownItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Segment unique identifier"},"name":{"type":"string","description":"Segment name"},"count":{"type":"number","description":"Number of releases in this segment"}},"required":["id","name","count"],"additionalProperties":false},"CatalogSegmentStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of segments"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSegmentBreakdownItem"},"description":"Breakdown of segments with release counts"}},"required":["total","breakdown"],"additionalProperties":false},"CatalogManufacturerBreakdownItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Manufacturer unique identifier"},"name":{"type":"string","description":"Manufacturer name"},"releaseCount":{"type":"number","description":"Number of releases by this manufacturer"}},"required":["id","name","releaseCount"],"additionalProperties":false},"CatalogManufacturerStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of manufacturers"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CatalogManufacturerBreakdownItem"},"description":"All manufacturers with their release counts"}},"required":["total","breakdown"],"additionalProperties":false},"CatalogReleaseYearBreakdown":{"type":"object","properties":{"year":{"type":"string","description":"Release year"},"count":{"type":"number","description":"Number of releases in this year for this segment"}},"required":["year","count"],"additionalProperties":false},"CatalogReleaseBySegment":{"type":"object","properties":{"segmentName":{"type":"string","description":"Segment name"},"total":{"type":"number","description":"Total releases in this segment across all years"},"byYear":{"type":"array","items":{"$ref":"#/components/schemas/CatalogReleaseYearBreakdown"},"description":"Year-by-year breakdown for this segment"}},"required":["segmentName","total","byYear"],"additionalProperties":false},"CatalogReleaseStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of releases across all years"},"bySegment":{"type":"array","items":{"$ref":"#/components/schemas/CatalogReleaseBySegment"},"description":"Breakdown by segment, then by year"}},"required":["total","bySegment"],"additionalProperties":false},"CatalogSetStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of card sets"},"identifiable":{"type":"number","description":"Number of sets that can be recognized by AI"}},"required":["total","identifiable"],"additionalProperties":false},"CatalogCardStats":{"type":"object","properties":{"total":{"type":"number","description":"Total cards including all parallel versions"},"base":{"type":"number","description":"Base cards (non-parallel, non-variation)"},"variations":{"type":"number","description":"Variation cards (non-parallel)"},"parallels":{"type":"number","description":"Total parallel card instances"}},"required":["total","base","variations","parallels"],"additionalProperties":false},"CatalogParallelStats":{"type":"object","properties":{"total":{"type":"number","description":"Total number of parallel types"},"fullSet":{"type":"number","description":"Count of full set parallels (apply to entire set)"},"partial":{"type":"number","description":"Count of partial parallels (apply to specific cards only)"}},"required":["total","fullSet","partial"],"additionalProperties":false},"CatalogStatisticsResponse":{"type":"object","properties":{"segments":{"description":"Segment statistics","$ref":"#/components/schemas/CatalogSegmentStats"},"manufacturers":{"description":"Manufacturer statistics","$ref":"#/components/schemas/CatalogManufacturerStats"},"releases":{"description":"Release statistics","$ref":"#/components/schemas/CatalogReleaseStats"},"sets":{"description":"Set statistics","$ref":"#/components/schemas/CatalogSetStats"},"cards":{"description":"Card statistics","$ref":"#/components/schemas/CatalogCardStats"},"parallels":{"description":"Parallel statistics","$ref":"#/components/schemas/CatalogParallelStats"}},"required":["segments","manufacturers","releases","sets","cards","parallels"],"additionalProperties":false},"CardWithOptionalParallel":{"type":"object","properties":{"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the release this card belongs to. Provided for convenience to avoid additional lookups."},"setId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"UUID of the set this card belongs to. Links to the set entity. Determines which collection within the release contains this card."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the card. Format: UUID v4. This ID is permanent and used for all API operations involving this card."},"number":{"description":"Card number within the set. Examples: \"23\", \"RC-15\", \"L-5\". May include letters for special subsets. Null for unnumbered cards.","type":"string"},"name":{"type":"string","description":"Primary subject of the card. Usually a player name for sports cards (e.g., \"Michael Jordan\") or character/subject for non-sports."},"description":{"description":"Additional card details such as team, position, special notations, or card back information. May be null.","type":"string"},"isParallelOnly":{"description":"Indicates this card exists only as a parallel, not as a base card. For example, if a set has 15 base cards but a parallel variant has 20 cards, the 5 extra cards would have isParallelOnly: true.","type":"boolean"},"setName":{"type":"string","description":"Name of the set this card belongs to"},"releaseName":{"description":"Name of the release","type":"string"},"releaseYear":{"description":"Year of the release","type":"string"},"attributes":{"description":"Array of attribute short names","type":"array","items":{"type":"string"}},"variationOf":{"description":"UUID of the base card if this is a variation. Only present for variation cards, omitted for base cards.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallels":{"description":"Simplified list of parallel variants for this card. Includes id, name, and numberedTo.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the parallel type. Format: UUID v4. This ID represents the parallel variant, not individual cards."},"name":{"type":"string","description":"Name of the parallel variant. Examples: \"Gold Refractor\", \"Black Prizm\", \"Orange\". Describes the visual variant or rarity tier."},"numberedTo":{"description":"Limited print run number for this parallel","type":"number"}},"required":["id","name"],"additionalProperties":false}},"fields":{"description":"Key-value field properties (e.g., HP, Rarity, Artist). Omitted when the card has no fields.","$ref":"#/components/schemas/FieldValues"},"isParallel":{"description":"True if this card was converted to a parallel variant through the random odds system","type":"boolean"},"parallelId":{"description":"UUID of the parallel type if this card is a parallel variant","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"parallelName":{"description":"Name of the parallel variant (e.g., \"Gold Refractor\", \"Black Prizm 1/1\")","type":"string"},"numberedTo":{"description":"Limited print run number for this parallel. Null for unlimited parallels.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["releaseId","setId","id","name","setName"],"additionalProperties":false},"RandomReleasesResponse":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseSummary"},"description":"Array of random releases matching the specified filters"},"count":{"type":"number","description":"Actual number of releases returned. May be less than requested count if insufficient matches."}},"required":["releases","count"],"additionalProperties":false},"RandomSetsResponse":{"type":"object","properties":{"sets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier for the set. Format: UUID v4. This ID is permanent and used for all API operations involving this set."},"name":{"type":"string","description":"Name of the set within the release. Examples: \"Base Set\", \"Rookie Autographs\", \"Legends\". Describes the theme or type of cards in this set."},"description":{"description":"Additional details about the set, such as card count, special features, or checklist highlights. May be null.","type":"string"},"is_identifiable":{"type":"boolean","description":"Whether cards in this set can be identified by the CardSightAI identification service."},"cardCount":{"type":"number","description":"Number of base cards in this set"},"parallelCount":{"type":"number","description":"Number of parallel types in this set"},"releaseId":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Release UUID"},"releaseName":{"type":"string","description":"Release name"},"releaseYear":{"type":"string","description":"Release year"}},"required":["id","name","is_identifiable","cardCount","parallelCount","releaseId","releaseName","releaseYear"],"additionalProperties":false},"description":"Array of random sets matching the specified filters"},"count":{"type":"number","description":"Actual number of sets returned. May be less than requested count if insufficient matches."}},"required":["sets","count"],"additionalProperties":false},"RandomCardsResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardWithOptionalParallel"},"description":"Array of random cards. When includeParallels=true, some cards may be converted to parallels based on weighted probability."},"count":{"type":"number","description":"Actual number of cards returned. May be less than requested count if insufficient matches."}},"required":["cards","count"],"additionalProperties":false},"SearchResult":{"type":"object","properties":{"type":{"type":"string","enum":["card","set","release","parallel"],"description":"Entity type of this search result."},"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Unique identifier (UUID) for this entity. Use this ID to fetch full details from the corresponding entity endpoint."},"name":{"type":"string","description":"Primary name of the entity. Player/subject name for cards, set name for sets, release name for releases."},"relevance":{"type":"number","description":"Relevance score combining full-text search rank and fuzzy similarity. Higher values indicate stronger matches. Results are sorted by this score descending."},"year":{"description":"Release year associated with this result.","type":"string"},"setName":{"description":"Set name. Present for card and parallel results.","type":"string"},"releaseName":{"description":"Release name. Present for card, set, and parallel results.","type":"string"},"manufacturerName":{"description":"Manufacturer name.","type":"string"},"parallelName":{"description":"Name of the matching parallel variant. Present when a parallel name contributed to this result's relevance.","type":"string"}},"required":["type","id","name","relevance"],"additionalProperties":false},"CatalogSearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"},"description":"Array of search results ordered by relevance score (descending). Contains a mix of cards, sets, and releases unless filtered by type."},"total_count":{"type":"number","description":"Total number of results matching the query across all included types."},"skip":{"type":"number","description":"Number of results skipped (offset) for pagination."},"take":{"type":"number","description":"Number of results included in this page."}},"required":["results","total_count","skip","take"],"additionalProperties":false},"AutocompleteResponse":{"type":"object","properties":{"suggestions":{"maxItems":10,"type":"array","items":{"type":"string"},"description":"List of autocomplete suggestions, maximum 10 items, sorted alphabetically"}},"required":["suggestions"],"additionalProperties":false},"GradingCompany":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grading company"},"name":{"type":"string","description":"Name of the grading company (e.g., PSA, BGS, SGC, CGC)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detailed description of the grading company and its services"}},"required":["id","name","description"],"additionalProperties":false},"GradingType":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grading type"},"gradingCompanyId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the parent grading company offering this grading type"},"gradingCompanyName":{"type":"string","description":"Name of the parent grading company (denormalized for convenience)"},"name":{"type":"string","description":"Name of the grading type (e.g., Regular, Crossover, Black Label)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detailed description of what this grading type offers or represents"}},"required":["id","gradingCompanyId","gradingCompanyName","name","description"],"additionalProperties":false},"Grade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the grade"},"gradingTypeId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the parent grading type that this grade belongs to"},"gradingTypeName":{"type":"string","description":"Name of the parent grading type (denormalized for convenience)"},"gradingCompanyId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"ID of the grading company (denormalized for convenience)"},"gradingCompanyName":{"type":"string","description":"Name of the grading company (denormalized for convenience)"},"grade":{"type":"string","description":"The grade value as a string (e.g., \"10\", \"9.5\", \"8\") to support decimal and \"Authentic\" grades"},"condition":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The condition descriptor for this grade (e.g., \"GEM MINT\", \"MINT\", \"PRISTINE\")"}},"required":["id","gradingTypeId","gradingTypeName","gradingCompanyId","gradingCompanyName","grade","condition"],"additionalProperties":false},"GradingCompaniesResponse":{"type":"object","properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/GradingCompany"},"description":"List of grading companies"},"total":{"type":"number","description":"Total number of grading companies available"}},"required":["companies","total"],"additionalProperties":false},"GradingTypesResponse":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/GradingType"},"description":"List of grading types offered by this company"},"total":{"type":"number","description":"Total number of grading types for this company"},"gradingCompany":{"description":"Parent grading company information for context","$ref":"#/components/schemas/GradingCompany"}},"required":["types","total","gradingCompany"],"additionalProperties":false},"GradesResponse":{"type":"object","properties":{"grades":{"type":"array","items":{"$ref":"#/components/schemas/Grade"},"description":"List of specific grade values available for this grading type"},"total":{"type":"number","description":"Total number of grades for this grading type"},"gradingType":{"description":"Parent grading type information for context","$ref":"#/components/schemas/GradingType"},"gradingCompany":{"description":"Grandparent grading company information for context","$ref":"#/components/schemas/GradingCompany"}},"required":["grades","total","gradingType","gradingCompany"],"additionalProperties":false},"BulkPricingRequest":{"type":"object","properties":{"card_ids":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Array of card UUIDs to fetch pricing for (1-100). Matches the max page size of catalog search results."},"parallel_id":{"description":"Filter by parallel variant UUID. null = base card only.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"grade_id":{"description":"Filter by grade UUID. null = ungraded only.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"period":{"default":"all","description":"Lookback period. Examples: \"7d\", \"14d\", \"2w\", \"3m\", \"1y\", \"all\". Omit or \"all\" for no time limit.","type":"string"},"listing_type":{"default":"both","description":"Filter by listing type. auction=completed auctions, fixed=buy-it-now, both=all","type":"string","enum":["auction","fixed","both"]},"limit":{"description":"Maximum number of records per card","type":"integer","exclusiveMinimum":0,"maximum":500}},"required":["card_ids","period","listing_type"],"additionalProperties":false},"PricingRecord":{"type":"object","properties":{"title":{"description":"Listing title from marketplace","anyOf":[{"type":"string"},{"type":"null"}]},"price":{"type":"number","minimum":0,"description":"Sale price in USD"},"date":{"description":"Sale date in ISO 8601 format","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","description":"Data source (e.g., \"ebay\")"},"listing_type":{"description":"Type of listing: auction or fixed price","anyOf":[{"type":"string","enum":["auction","fixed"]},{"type":"null"}]},"url":{"description":"URL to the original listing","anyOf":[{"type":"string"},{"type":"null"}]},"image_url":{"description":"Primary image URL for the listing","anyOf":[{"type":"string"},{"type":"null"}]},"parallel_id":{"description":"Parallel variant UUID. Null for base card listings.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parallel_name":{"description":"Parallel variant name. Null for base card listings.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["price","source"],"additionalProperties":false},"MarketplaceRecord":{"type":"object","properties":{"title":{"type":"string","description":"Listing title"},"price":{"description":"Current price or starting bid in USD","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"source":{"type":"string","description":"Marketplace source"},"listing_type":{"description":"Type of listing","anyOf":[{"type":"string","enum":["auction","fixed","search"]},{"type":"null"}]},"url":{"description":"URL to the listing","anyOf":[{"type":"string"},{"type":"null"}]},"image_url":{"description":"Primary image URL","anyOf":[{"type":"string"},{"type":"null"}]},"condition":{"description":"Condition description from seller","anyOf":[{"type":"string"},{"type":"null"}]},"end_date":{"description":"Listing end date in ISO 8601 format","anyOf":[{"type":"string"},{"type":"null"}]},"bid_count":{"description":"Number of bids (auctions only)","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"parallel_id":{"description":"Parallel variant UUID. Null for base card listings.","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parallel_name":{"description":"Parallel variant name. Null for base card listings.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title","source"],"additionalProperties":false},"PricingCardContext":{"type":"object","properties":{"card_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Card UUID"},"name":{"type":"string","description":"Card name/subject"},"number":{"description":"Card number in set","anyOf":[{"type":"string"},{"type":"null"}]},"set":{"type":"object","properties":{"set_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Set UUID"},"name":{"type":"string","description":"Set name"},"year":{"type":"string","description":"Release year"},"release":{"type":"string","description":"Release name"}},"required":["set_id","name","year","release"],"additionalProperties":false,"description":"Set context"},"parallel":{"description":"Parallel context if filtered by parallel","anyOf":[{"type":"object","properties":{"parallel_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Parallel UUID"},"name":{"type":"string","description":"Parallel name"}},"required":["parallel_id","name"],"additionalProperties":false},{"type":"null"}]}},"required":["card_id","name","set"],"additionalProperties":false},"PricingQueryEcho":{"type":"object","properties":{"parallel_id":{"description":"Parallel UUID filter applied","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"grade_id":{"description":"Grade UUID filter applied","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"period":{"description":"Period filter applied (pricing only)","type":"string"},"listing_type":{"description":"Listing type filter applied","type":"string"},"as_of_date":{"type":"string","description":"Date the data was retrieved"}},"required":["as_of_date"],"additionalProperties":false},"SourceBreakdownItem":{"type":"object","properties":{"source":{"type":"string","description":"Source name"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records from this source"}},"required":["source","count"],"additionalProperties":false},"PricingMeta":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceBreakdownItem"},"description":"Breakdown by data source"},"last_sale_date":{"description":"Date of most recent sale","anyOf":[{"type":"string"},{"type":"null"}]},"total_records":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total records returned across all sections"}},"required":["sources","total_records"],"additionalProperties":false},"RawPricingSection":{"type":"object","properties":{"period_days":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Period in days that was applied"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records"},"records":{"type":"array","items":{"$ref":"#/components/schemas/PricingRecord"},"description":"Pricing records for ungraded cards"}},"required":["period_days","count","records"],"additionalProperties":false},"PricingGradeGroup":{"type":"object","properties":{"grade_value":{"type":"string","description":"Grade value (e.g., \"10\", \"9.5\")"},"grade_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grade UUID"},"period_days":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Period in days that was applied"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of records in this group"},"records":{"type":"array","items":{"$ref":"#/components/schemas/PricingRecord"},"description":"Pricing records for this grade"}},"required":["grade_value","grade_id","period_days","count","records"],"additionalProperties":false},"PricingCompanyGroup":{"type":"object","properties":{"company_name":{"type":"string","description":"Grading company name (e.g., \"PSA\")"},"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grading company UUID"},"grades":{"type":"array","items":{"$ref":"#/components/schemas/PricingGradeGroup"},"description":"Grade groups for this company"}},"required":["company_name","company_id","grades"],"additionalProperties":false},"PricingResponse":{"type":"object","properties":{"card":{"description":"Card context information","$ref":"#/components/schemas/PricingCardContext"},"query":{"description":"Echo of query parameters applied","$ref":"#/components/schemas/PricingQueryEcho"},"raw":{"description":"Ungraded/raw pricing data","$ref":"#/components/schemas/RawPricingSection"},"graded":{"type":"array","items":{"$ref":"#/components/schemas/PricingCompanyGroup"},"description":"Graded pricing data grouped by company and grade"},"meta":{"description":"Response metadata","$ref":"#/components/schemas/PricingMeta"}},"required":["card","query","raw","graded","meta"],"additionalProperties":false},"RawMarketplaceSection":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of active listings"},"records":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceRecord"},"description":"Active marketplace listings"}},"required":["count","records"],"additionalProperties":false},"MarketplaceGradeGroup":{"type":"object","properties":{"grade_value":{"type":"string","description":"Grade value"},"grade_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grade UUID"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of listings"},"records":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceRecord"},"description":"Active listings for this grade"}},"required":["grade_value","grade_id","count","records"],"additionalProperties":false},"MarketplaceCompanyGroup":{"type":"object","properties":{"company_name":{"type":"string","description":"Grading company name"},"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Grading company UUID"},"grades":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceGradeGroup"},"description":"Grade groups"}},"required":["company_name","company_id","grades"],"additionalProperties":false},"MarketplaceMeta":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceBreakdownItem"},"description":"Breakdown by data source"},"total_records":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Total records returned"}},"required":["sources","total_records"],"additionalProperties":false},"MarketplaceResponse":{"type":"object","properties":{"card":{"description":"Card context information","$ref":"#/components/schemas/PricingCardContext"},"query":{"description":"Echo of query parameters applied","$ref":"#/components/schemas/PricingQueryEcho"},"raw":{"description":"Ungraded active listings","$ref":"#/components/schemas/RawMarketplaceSection"},"graded":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceCompanyGroup"},"description":"Graded active listings grouped by company and grade"},"meta":{"description":"Response metadata","$ref":"#/components/schemas/MarketplaceMeta"}},"required":["card","query","raw","graded","meta"],"additionalProperties":false},"BulkPricingResult":{"type":"object","properties":{"card_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Card UUID"},"success":{"type":"boolean","description":"Whether pricing was successfully retrieved"},"data":{"description":"Pricing data when successful","$ref":"#/components/schemas/PricingResponse"},"error":{"description":"Error details when unsuccessful","type":"object","properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"}},"required":["code","message"],"additionalProperties":false}},"required":["card_id","success"],"additionalProperties":false},"BulkPricingResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkPricingResult"},"description":"Pricing results for each requested card"},"meta":{"type":"object","properties":{"requested":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards requested"},"successful":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards with successful results"},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of cards that failed"}},"required":["requested","successful","failed"],"additionalProperties":false,"description":"Summary counts"}},"required":["results","meta"],"additionalProperties":false},"ReleaseCalendarEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Unique identifier for the release calendar entry"},"name":{"type":"string","description":"Name of the release"},"year":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Release year"},"release_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Expected or actual release date (YYYY-MM-DD)"},"pre_order_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Date when pre-orders open (YYYY-MM-DD)"},"segment_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Unique identifier of the associated market segment"},"manufacturer_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"Unique identifier of the associated manufacturer"}},"required":["id","name","year","release_date","pre_order_date","segment_id","manufacturer_id"],"additionalProperties":false},"PaginatedReleaseCalendarResponse":{"type":"object","properties":{"release_calendar":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseCalendarEntry"},"description":"List of release calendar entries"},"total_count":{"type":"number","description":"Total number of entries matching the query"},"skip":{"type":"number","description":"Number of items skipped (offset)"},"take":{"type":"number","description":"Number of items included in this page"}},"required":["release_calendar","total_count","skip","take"],"additionalProperties":false},"BasicHealthResponse":{"type":"object","properties":{"status":{"type":"string","description":"Overall health status of the API (e.g., \"healthy\")"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when the health check was performed"}},"required":["status","timestamp"],"additionalProperties":false}}},"paths":{"/health":{"get":{"operationId":"getHealth","summary":"Basic health check","tags":["Health"],"description":"Returns the current health status of the service","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicHealthResponse"}}}}}}},"/health/auth":{"get":{"operationId":"getHealthAuthenticated","summary":"Authenticated health check","tags":["Health"],"description":"Returns the current health status of the service. Requires a valid API key to access. Use this endpoint to validate that your API key is configured correctly.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicHealthResponse"}}}}}}},"/v1/detect/card":{"post":{"operationId":"detectCard","summary":"Detect trading card presence in an image","tags":["Card Detection"],"description":"Checks whether one or more trading cards are present in the submitted image. Returns a boolean detected flag and card count. Does not identify or catalog the cards. Supports both multipart/form-data and direct binary upload (image/jpeg, image/png, image/webp). Maximum file size: 20MB.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/jpeg":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/png":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/webp":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectCardResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/identify/card":{"post":{"operationId":"identifyCard","summary":"Identifies a card from the submitted image (defaults to baseball)","tags":["Card Identification"],"description":"Identify a card from an image. Defaults to the baseball segment. Use POST /card/:segment for other sports. Supports both multipart/form-data and direct binary upload (image/jpeg, image/png, image/webp). Maximum file size: 20MB. Supported formats: JPEG, PNG, WebP, HEIF, HEIC.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/jpeg":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/png":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/webp":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyCardResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/identify/card/{segment}":{"post":{"operationId":"identifyCardBySegment","summary":"Identifies a card from the submitted image for a specific segment (sport)","tags":["Card Identification"],"description":"Identify a card from an image for a specific segment (sport). The segment can be specified by UUID or name (case-insensitive, e.g., \"football\", \"basketball\"). Supports both multipart/form-data and direct binary upload (image/jpeg, image/png, image/webp). Maximum file size: 20MB. Supported formats: JPEG, PNG, WebP, HEIF, HEIC.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/jpeg":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/png":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}},"image/webp":{"schema":{"$ref":"#/components/schemas/FileUploadInput"}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"segment","required":true,"description":"Segment identifier - either a UUID or segment name (e.g., \"football\", \"baseball\")"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyCardResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/statistics":{"get":{"operationId":"getStatistics","summary":"Get comprehensive catalog statistics","tags":["Catalog"],"description":"\n# Catalog Statistics\n\nThis endpoint provides comprehensive statistics about the entire card catalog database.\n\n**Purpose:**\nCollectors can view high-level metrics to understand the scope and breadth of the CardSight AI catalog. This helps inform collecting strategies by showing:\n- What segments and manufacturers are available\n- How many releases exist per year\n- The depth of card data (base cards vs parallels vs variations)\n- AI identification capabilities\n\n**Response Structure:**\n\n**Segments:**\n- Total count of sports/card segments\n- Breakdown showing each segment name with release count\n\n**Manufacturers:**\n- Total count of card manufacturers\n- All manufacturers with their release counts\n\n**Releases:**\n- Total count across all years\n- Breakdown by segment with total releases per segment\n- Within each segment, year-by-year breakdown of release counts\n\n**Sets:**\n- Total count of card sets\n- Count of identifiable sets (sets that can be recognized by AI)\n\n**Cards:**\n- Total count of all cards in catalog\n- Count of base cards (original cards)\n- Count of variations (alternate versions of base cards)\n\n**Parallels:**\n- Total count of parallel types\n- Count of full set parallels (apply to entire set)\n- Count of partial parallels (apply to specific cards only)\n\n**Caching:**\nThis endpoint is cached for 1 hour to optimize performance since catalog statistics change infrequently.\n\n**Use Cases:**\n- Understanding catalog coverage before starting a collection\n- Identifying which manufacturers have the most complete data\n- Seeing historical trends in releases by year\n- Gauging AI identification capabilities for specific sets\n","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogStatisticsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/search":{"get":{"operationId":"searchCatalog","summary":"Search across cards, sets, releases, and parallels","tags":["Catalog"],"description":"Global fuzzy search endpoint that searches across card names, set names, release names, parallel names, manufacturer names, and years simultaneously. Supports multi-word queries like \"aaron judge topps\", \"1952 mickey mantle\", or \"refractor\". Uses PostgreSQL full-text search combined with trigram similarity for typo-tolerant matching. Results are ranked by relevance and returned as a mixed list of cards, sets, releases, and parallels. Cards and sets that match a parallel name (e.g., \"Refractor\") are boosted in relevance and include the matching parallelName in the response. Use the \"type\" parameter to filter to a specific entity type.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","minLength":2,"maxLength":200},"in":"query","name":"q","required":true,"description":"Free-text search query. Searches across card names, set names, release names, manufacturer names, and years simultaneously. Supports multi-word queries like \"aaron judge topps\" or \"1952 mickey mantle\". Minimum 2 characters."},{"schema":{"type":"string","enum":["card","set","release","parallel"]},"in":"query","name":"type","required":false,"description":"Filter results to a specific entity type. When omitted, returns mixed results across all types."},{"schema":{"type":"string"},"in":"query","name":"segment","required":false,"description":"Filter by segment. Accepts either a UUID or exact segment name (case-insensitive)."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter by manufacturer. Accepts either a UUID or exact manufacturer name (case-insensitive)."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter results from this year onwards (inclusive). Ignored if \"year\" is specified."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter results up to this year (inclusive). Ignored if \"year\" is specified."},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"field","required":false,"description":"Filter card results by field key/value pairs. Repeat the parameter for multiple fields — all must match (AND). Format: KEY:VALUE. Example: field=CASTING_COST:2&field=COLOR:Red. Keys are normalized to uppercase; values match case-insensitively. When this parameter is set, results are restricted to cards (other entity types are excluded), since field metadata is only modeled on cards."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/segments":{"get":{"operationId":"getSegments","summary":"List market segments","tags":["Catalog"],"description":"Retrieve a paginated list of market segments (categories) for trading cards. Segments are the highest level of organization, representing markets like Baseball, Pokemon, Magic The Gathering, etc. Use this endpoint to get available segments for filtering releases or building category navigation. Segments can be searched by name and sorted alphabetically. Each segment may contain multiple manufacturers and releases.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter segments by name using partial string matching. Case-insensitive. Example: \"sport\" matches \"Sports\", \"Motorsports\", etc."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_identifiable","required":false,"description":"Filter segments by identifiability. \"true\" returns only segments that can be identified by AI, \"false\" returns only non-identifiable segments."},{"schema":{"type":"string","enum":["name"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. Currently only supports sorting by segment name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (A-Z), \"desc\" for descending (Z-A). Defaults to ascending."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSegmentsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSegmentsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/manufacturers":{"get":{"operationId":"getManufacturers","summary":"List card manufacturers","tags":["Catalog"],"description":"Retrieve a paginated list of trading card manufacturers/companies. Manufacturers are companies that produce trading cards (e.g., Topps, Panini, Upper Deck). Use this endpoint to get available manufacturers for filtering releases or understanding the card market landscape. Manufacturers can be searched by name and sorted alphabetically. Each manufacturer may have releases across multiple segments and years.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter manufacturers by name using partial string matching. Case-insensitive. Example: \"top\" matches \"Topps\", \"Topps Chrome\", etc."},{"schema":{"type":"string","enum":["name"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. Currently only supports sorting by manufacturer name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (A-Z), \"desc\" for descending (Z-A). Defaults to ascending."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedManufacturersResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedManufacturersResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/releases":{"get":{"operationId":"getReleases","summary":"Browse and search Releases with pagination","tags":["Catalog"],"description":"Browse and search Releases with pagination","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"segment","required":false,"description":"Filter releases by segment. Accepts either a UUID (e.g., \"550e8400-e29b-41d4-a716-446655440000\") or exact segment name (e.g., \"Sports\"). Case-insensitive for names."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter releases by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Case-insensitive for names."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter by exact year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter releases from this year onwards (inclusive). Example: \"2020\" returns releases from 2020, 2021, 2022, etc. Ignored if \"year\" is specified."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter releases up to this year (inclusive). Example: \"2022\" returns releases from 2022 and earlier. Ignored if \"year\" is specified."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search releases by name using partial string matching. Case-insensitive. Example: \"chrome\" matches \"Topps Chrome\", \"Bowman Chrome\", etc."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_identifiable","required":false,"description":"Filter releases by identifiability. \"true\" returns releases with at least one AI-identifiable set, \"false\" returns releases with no identifiable sets."},{"schema":{"type":"string","enum":["year","name"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"year\" sorts by release year, \"name\" sorts alphabetically by release name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (oldest first for year, A-Z for name), \"desc\" for descending (newest first for year, Z-A for name)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReleasesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReleasesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/releases/{id}":{"get":{"operationId":"getRelease","summary":"Get detailed information about a specific Release","tags":["Catalog"],"description":"Get detailed information about a specific Release including Sets and Card counts","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Unique identifier for the release. Must be a valid UUID format. Example: \"550e8400-e29b-41d4-a716-446655440000\""}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedReleaseResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedReleaseResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/releases/{id}/cards":{"get":{"operationId":"getReleaseCards","summary":"List all cards in a release","tags":["Catalog"],"description":"Retrieve a paginated list of all base cards (not parallels) within a specific release across all its sets. Use the optional setId parameter to filter to a specific set within the release. Cards can be searched by player name and sorted by card number or name. This endpoint is ideal for building complete checklists, player searches within a release, or browsing all cards in a product.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"setId","required":false,"description":"Filter cards to a specific set within the release. Must be a valid UUID. Example: \"550e8400-e29b-41d4-a716-446655440000\""},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search cards by player/subject name using partial string matching. Case-insensitive. Example: \"jordan\" matches \"Michael Jordan\", \"Jordan Love\", etc."},{"schema":{"type":"string","enum":["number","name"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"number\" sorts by card number in set, \"name\" sorts alphabetically by player/subject name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (1-999 for number, A-Z for name), \"desc\" for descending (999-1 for number, Z-A for name)."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Unique identifier for the release. Must be a valid UUID format. Example: \"550e8400-e29b-41d4-a716-446655440000\""}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/releases/random":{"get":{"operationId":"getRandomReleases","summary":"Get random releases matching filters","tags":["Catalog"],"description":"Returns random releases instead of paginated sorted results. Useful for discovery features, random browsing, or showcasing variety in the catalog. Supports all standard release filters including year, manufacturer, segment, and name search. If count exceeds available matching releases, returns all available releases.","parameters":[{"schema":{"type":"string"},"in":"query","name":"segment","required":false,"description":"Filter releases by segment. Accepts either a UUID (e.g., \"550e8400-e29b-41d4-a716-446655440000\") or exact segment name (e.g., \"Sports\"). Case-insensitive for names."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter releases by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Case-insensitive for names."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter by exact year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter releases from this year onwards (inclusive). Example: \"2020\" returns releases from 2020, 2021, 2022, etc. Ignored if \"year\" is specified."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter releases up to this year (inclusive). Example: \"2022\" returns releases from 2022 and earlier. Ignored if \"year\" is specified."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search releases by name using partial string matching. Case-insensitive. Example: \"chrome\" matches \"Topps Chrome\", \"Bowman Chrome\", etc."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_identifiable","required":false,"description":"Filter releases by identifiability. \"true\" returns releases with at least one AI-identifiable set, \"false\" returns releases with no identifiable sets."},{"schema":{"type":"string","enum":["year","name"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"year\" sorts by release year, \"name\" sorts alphabetically by release name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (oldest first for year, A-Z for name), \"desc\" for descending (newest first for year, Z-A for name)."},{"schema":{"default":1,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"count","required":false,"description":"Number of random releases to return. Minimum: 1, Maximum: 200, Default: 1. If fewer releases match filters, returns all available."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomReleasesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomReleasesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/sets":{"get":{"operationId":"getSets","summary":"List and search card sets","tags":["Catalog"],"description":"Retrieve a paginated list of card sets across all releases. Sets represent collections within releases (e.g., \"Base Set\", \"Rookie Autographs\"). Filter by release, year range, manufacturer, or search by name. Results include card and parallel counts for each set. Use this endpoint to explore available sets, build set checklists, or filter sets by specific criteria. Each set belongs to exactly one release.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter sets to a specific release. Must be a valid UUID. Example: \"550e8400-e29b-41d4-a716-446655440000\""},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search sets by name using partial string matching. Case-insensitive. Example: \"base\" matches \"Base Set\", \"Base Chrome\", etc."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter sets by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter sets from releases in this year onwards (inclusive). Example: \"2020\" returns sets from 2020, 2021, 2022 releases, etc."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter sets from releases up to this year (inclusive). Example: \"2022\" returns sets from 2022 and earlier releases."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter sets by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Filters through the release relationship."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_identifiable","required":false,"description":"Filter sets by identifiability. \"true\" returns only sets that can be identified by AI, \"false\" returns only non-identifiable sets."},{"schema":{"type":"string","enum":["name","year"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" sorts by set name, \"year\" sorts by release year then set name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending, \"desc\" for descending."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSetsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSetsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/sets/{id}":{"get":{"operationId":"getSet","summary":"Get complete set details","tags":["Catalog"],"description":"Retrieve comprehensive information about a specific set including its release context, card count, and all parallel variants. Returns the set details along with release information (name, year) and a complete list of parallel types available for cards in this set. Use this endpoint for detailed set views, understanding set composition, or displaying complete set information with all variants.","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Set UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedSetResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedSetResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/sets/{id}/cards":{"get":{"operationId":"getSetCards","summary":"List cards within a set","tags":["Catalog"],"description":"Retrieve a paginated list of all base cards within a specific set. Cards can be filtered by player name or card number, and sorted by number or name. This endpoint returns only the base versions of cards, not their parallel variants. Use this for building set checklists, finding specific cards within a set, or displaying complete set contents. Each card includes its number, name, and basic information.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search by card name (partial match)"},{"schema":{"type":"string"},"in":"query","name":"number","required":false,"description":"Filter by card number"},{"schema":{"type":"string","enum":["number","name"]},"in":"query","name":"sort","required":false,"description":"Field to sort by"},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Set UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/sets/random":{"get":{"operationId":"getRandomSets","summary":"Get random sets matching filters","tags":["Catalog"],"description":"Returns random sets instead of paginated sorted results. Useful for discovery features or showcasing catalog variety. Supports all standard set filters including release, year range, manufacturer, and name search. Each set includes its release context and card/parallel counts. If count exceeds available matching sets, returns all available sets.","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter sets to a specific release. Must be a valid UUID. Example: \"550e8400-e29b-41d4-a716-446655440000\""},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search sets by name using partial string matching. Case-insensitive. Example: \"base\" matches \"Base Set\", \"Base Chrome\", etc."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter sets by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter sets from releases in this year onwards (inclusive). Example: \"2020\" returns sets from 2020, 2021, 2022 releases, etc."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter sets from releases up to this year (inclusive). Example: \"2022\" returns sets from 2022 and earlier releases."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter sets by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Filters through the release relationship."},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_identifiable","required":false,"description":"Filter sets by identifiability. \"true\" returns only sets that can be identified by AI, \"false\" returns only non-identifiable sets."},{"schema":{"type":"string","enum":["name","year"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" sorts by set name, \"year\" sorts by release year then set name."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending, \"desc\" for descending."},{"schema":{"default":1,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"count","required":false,"description":"Number of random sets to return. Minimum: 1, Maximum: 200, Default: 1. If fewer sets match filters, returns all available."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomSetsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomSetsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/cards":{"get":{"operationId":"getCards","summary":"Search cards across entire catalog","tags":["Catalog"],"description":"Global search endpoint for finding base cards across all releases, sets, and manufacturers. Supports complex filtering by player name, card number, release, set, year range, manufacturer, and attributes. Results include card details with release and set information. This is the primary endpoint for card discovery, player collections, and cross-product searches. Use specific release or set endpoints for more focused searches.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search cards by player/subject name using partial string matching. Case-insensitive. Example: \"lebron\" matches \"LeBron James\", \"LeBron James Jr.\", etc."},{"schema":{"type":"string"},"in":"query","name":"number","required":false,"description":"Filter by exact card number. Example: \"23\" returns all cards numbered 23 across all sets."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter cards to a specific release. Must be a valid UUID. Example: \"550e8400-e29b-41d4-a716-446655440000\""},{"schema":{"type":"string"},"in":"query","name":"releaseName","required":false,"description":"Filter cards by release name using partial string matching. Case-insensitive. Example: \"chrome\" matches cards from \"Topps Chrome\", \"Bowman Chrome\", etc."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter cards by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter cards from releases in this year onwards (inclusive). Example: \"2020\" returns cards from 2020, 2021, 2022 releases, etc."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter cards from releases up to this year (inclusive). Example: \"2022\" returns cards from 2022 and earlier releases."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"setId","required":false,"description":"Filter cards to a specific set. Must be a valid UUID. More specific than releaseId filter."},{"schema":{"type":"string"},"in":"query","name":"setName","required":false,"description":"Filter cards by set name using partial string matching. Case-insensitive. Example: \"rookie\" matches cards from \"Rated Rookies\", \"Rookie Stars\", etc."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter cards by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Filters through the release relationship."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"attributeId","required":false,"description":"Filter cards by attribute UUID. Returns only cards tagged with this specific attribute (e.g., Rookie Card, Autograph, etc.)"},{"schema":{"type":"string"},"in":"query","name":"attributeShortName","required":false,"description":"Filter cards by attribute short name/code. Example: \"RC\" for Rookie Cards, \"AU\" for Autographs. Case-sensitive."},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"field","required":false,"description":"Filter cards by field key/value pairs. Repeat the parameter for multiple fields — all must match (AND). Format: KEY:VALUE. Example: field=CASTING_COST:2&field=COLOR:Red. Keys are normalized to uppercase; values match case-insensitively."},{"schema":{"type":"string","enum":["name","release","set","year"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" = player name, \"release\" = release name, \"set\" = set name, \"year\" = release year."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending, \"desc\" for descending."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/cards/{id}":{"get":{"operationId":"getCard","summary":"Get complete card details","tags":["Catalog"],"description":"Retrieve comprehensive information about a specific card including its release, set, attributes, and available parallel variants. Returns full card details with contextual information about where it belongs in the catalog hierarchy. Includes a count of parallel versions available and all attributes (Rookie, Autograph, etc.) associated with the card. Use this endpoint for detailed card views, collection management, or when you need complete card information.","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Card UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedCardResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedCardResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/cards/random":{"get":{"operationId":"getRandomCards","summary":"Get random cards with optional parallel conversion","tags":["Catalog"],"description":"Simulates pack opening experience by returning random cards from the catalog. When includeParallels=true, each card has a weighted probability of converting to a parallel based on the parallel's numberedTo value. Parallels are checked from rarest to most common using a cascading algorithm where lower numbered parallels (e.g., 1/1) are significantly rarer than higher numbered ones (e.g., /999), and unlimited parallels are the most common. Supports comprehensive filtering by set, release, player name, year, manufacturer, and card attributes. Note: setId and releaseId filters are mutually exclusive.","parameters":[{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search cards by player/subject name using partial string matching. Case-insensitive. Example: \"lebron\" matches \"LeBron James\", \"LeBron James Jr.\", etc."},{"schema":{"type":"string"},"in":"query","name":"number","required":false,"description":"Filter by exact card number. Example: \"23\" returns all cards numbered 23 across all sets."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter cards to a specific release. Must be a valid UUID. Example: \"550e8400-e29b-41d4-a716-446655440000\""},{"schema":{"type":"string"},"in":"query","name":"releaseName","required":false,"description":"Filter cards by release name using partial string matching. Case-insensitive. Example: \"chrome\" matches cards from \"Topps Chrome\", \"Bowman Chrome\", etc."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter cards by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter cards from releases in this year onwards (inclusive). Example: \"2020\" returns cards from 2020, 2021, 2022 releases, etc."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter cards from releases up to this year (inclusive). Example: \"2022\" returns cards from 2022 and earlier releases."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"setId","required":false,"description":"Filter cards to a specific set. Must be a valid UUID. More specific than releaseId filter."},{"schema":{"type":"string"},"in":"query","name":"setName","required":false,"description":"Filter cards by set name using partial string matching. Case-insensitive. Example: \"rookie\" matches cards from \"Rated Rookies\", \"Rookie Stars\", etc."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter cards by manufacturer. Accepts either a UUID or exact manufacturer name (e.g., \"Topps\", \"Panini\"). Filters through the release relationship."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"attributeId","required":false,"description":"Filter cards by attribute UUID. Returns only cards tagged with this specific attribute (e.g., Rookie Card, Autograph, etc.)"},{"schema":{"type":"string"},"in":"query","name":"attributeShortName","required":false,"description":"Filter cards by attribute short name/code. Example: \"RC\" for Rookie Cards, \"AU\" for Autographs. Case-sensitive."},{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"field","required":false,"description":"Filter cards by field key/value pairs. Repeat the parameter for multiple fields — all must match (AND). Format: KEY:VALUE. Example: field=CASTING_COST:2&field=COLOR:Red. Keys are normalized to uppercase; values match case-insensitively."},{"schema":{"type":"string","enum":["name","release","set","year"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" = player name, \"release\" = release name, \"set\" = set name, \"year\" = release year."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending, \"desc\" for descending."},{"schema":{"default":1,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"count","required":false,"description":"Number of random cards to return. Minimum: 1, Maximum: 200, Default: 1. If fewer cards match filters, returns all available."},{"schema":{"default":false,"type":"boolean"},"in":"query","name":"includeParallels","required":false,"description":"Enable parallel odds system. When true, each card has a weighted chance to convert to a parallel based on the parallel's numberedTo value. Lower numbered parallels (e.g., 1/1) are rarer than higher numbered ones (e.g., /999), and unlimited parallels are the most common."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RandomCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/attributes":{"get":{"operationId":"getAttributes","summary":"Browse and search Attributes with card counts","tags":["Catalog"],"description":"Browse and search Attributes with pagination and card count information","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search attributes by full name using partial string matching. Case-insensitive. Example: \"rookie\" matches \"Rookie Card\", \"Rookie Year\", etc."},{"schema":{"type":"string"},"in":"query","name":"shortName","required":false,"description":"Search attributes by short name/code using partial string matching. Case-insensitive. Example: \"R\" matches \"RC\" (Rookie Card), \"RPA\" (Rookie Patch Auto), etc."},{"schema":{"type":"string","enum":["name","shortName","cardCount"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" = full name, \"shortName\" = abbreviation, \"cardCount\" = number of cards with this attribute."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (A-Z, lowest count first), \"desc\" for descending (Z-A, highest count first)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAttributesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAttributesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/attributes/{id}":{"get":{"operationId":"getAttributeById","summary":"Get detailed information about a specific Attribute","tags":["Catalog"],"description":"Get detailed information about a specific Attribute including card count","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Attribute UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedAttributeResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedAttributeResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/fields":{"get":{"operationId":"getFields","summary":"Browse and search Fields with usage counts","tags":["Catalog"],"description":"Browse and search Fields with pagination and combined usage counts across cards, sets, releases, and segments","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search fields by display name using partial string matching. Case-insensitive. Example: \"points\" matches \"Hit Points\", \"Attack Points\"."},{"schema":{"type":"string"},"in":"query","name":"key","required":false,"description":"Search fields by key using partial string matching. Case-insensitive. Example: \"hp\" matches fields with keys \"HP\", \"SHP\", etc."},{"schema":{"type":"string","enum":["name","key","usageCount"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" = display name, \"key\" = field key, \"usageCount\" = total usage across cards, sets, releases, and segments."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending (A-Z, lowest count first), \"desc\" for descending (Z-A, highest count first)."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFieldsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFieldsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/fields/{id}":{"get":{"operationId":"getFieldById","summary":"Get detailed information about a specific Field","tags":["Catalog"],"description":"Get detailed information about a specific Field including combined usage count","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Field UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedFieldResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedFieldResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/parallels":{"get":{"operationId":"getParallels","summary":"Search for parallels across sets and releases","tags":["Catalog"],"description":"Search for parallels by name and filter by release. Returns all sets containing the parallel with release information","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search parallels by name using partial string matching. Case-insensitive. Example: \"gold\" matches \"Gold Refractor\", \"Gold Prizm\", etc."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter parallels to a specific release. Must be a valid UUID. Returns all parallel types across all sets in the release."},{"schema":{"type":"string"},"in":"query","name":"releaseName","required":false,"description":"Filter parallels by release name using partial string matching. Case-insensitive. Example: \"prizm\" matches parallels from \"Prizm Basketball\", \"Prizm Football\", etc."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter parallels by exact release year (e.g., \"2023\"). When specified, overrides min_year and max_year parameters."},{"schema":{"type":"string"},"in":"query","name":"min_year","required":false,"description":"Filter parallels from releases in this year onwards (inclusive). Example: \"2020\" returns parallels from 2020, 2021, 2022 releases, etc."},{"schema":{"type":"string"},"in":"query","name":"max_year","required":false,"description":"Filter parallels from releases up to this year (inclusive). Example: \"2022\" returns parallels from 2022 and earlier releases."},{"schema":{"type":"string","enum":["name","release","set","year"]},"in":"query","name":"sort","required":false,"description":"Field to sort results by. \"name\" = parallel name, \"release\" = release name, \"set\" = set name, \"year\" = release year."},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort direction. \"asc\" for ascending, \"desc\" for descending."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedParallelsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedParallelsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/catalog/parallels/{id}":{"get":{"operationId":"getParallel","summary":"Get detailed parallel information","tags":["Catalog"],"description":"Retrieve detailed information about a specific Parallel, including set and release context. For partial parallels (isPartial=true), the response includes an array of Card IDs that have this Parallel.","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"id","required":true,"description":"Unique identifier for the parallel type. Must be a valid UUID format. Example: \"550e8400-e29b-41d4-a716-446655440000\""}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedParallelResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedParallelResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/segments":{"get":{"operationId":"autocompleteSegments","summary":"Segment name autocomplete","tags":["Autocomplete"],"description":"Get segment name suggestions for autocomplete. Returns up to 10 matching segment names sorted alphabetically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/manufacturers":{"get":{"operationId":"autocompleteManufacturers","summary":"Manufacturer name autocomplete","tags":["Autocomplete"],"description":"Get manufacturer name suggestions for autocomplete. Can filter by segment. Returns up to 10 matching manufacturer names sorted alphabetically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"segmentId","required":false,"description":"Filter manufacturers by segment UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/years":{"get":{"operationId":"autocompleteYears","summary":"Year autocomplete","tags":["Autocomplete"],"description":"Get year suggestions for autocomplete. Can filter by segment and/or manufacturer. Returns up to 10 matching years sorted chronologically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"segmentId","required":false,"description":"Filter years by segment UUID"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"manufacturerId","required":false,"description":"Filter years by manufacturer UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/releases":{"get":{"operationId":"autocompleteReleases","summary":"Release name autocomplete","tags":["Autocomplete"],"description":"Get release name suggestions for autocomplete. Can filter by segment, manufacturer, and/or year. Returns up to 10 matching release names sorted alphabetically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"segmentId","required":false,"description":"Filter releases by segment UUID"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"manufacturerId","required":false,"description":"Filter releases by manufacturer UUID"},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter releases by year (e.g., \"2023\")"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/sets":{"get":{"operationId":"autocompleteSets","summary":"Set name autocomplete","tags":["Autocomplete"],"description":"Get set name suggestions for autocomplete. Can filter by release, or broader filters like segment, manufacturer, and year. Returns up to 10 matching set names sorted alphabetically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter sets by release UUID"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"segmentId","required":false,"description":"Filter sets by segment UUID (when releaseId not provided)"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"manufacturerId","required":false,"description":"Filter sets by manufacturer UUID (when releaseId not provided)"},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter sets by year (when releaseId not provided)"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/autocomplete/cards":{"get":{"operationId":"autocompleteCards","summary":"Card name autocomplete","tags":["Autocomplete"],"description":"Get card name suggestions for autocomplete. Can filter by set, release, or broader filters. Returns up to 10 unique card names sorted alphabetically.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true,"description":"Search query string. Minimum 1 character for autocomplete suggestions."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"setId","required":false,"description":"Filter cards by set UUID"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"releaseId","required":false,"description":"Filter cards by release UUID (when setId not provided)"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"segmentId","required":false,"description":"Filter cards by segment UUID (for broader search)"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"manufacturerId","required":false,"description":"Filter cards by manufacturer UUID (for broader search)"},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter cards by year (for broader search)"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collectors/":{"post":{"operationId":"createCollector","summary":"Create a new collector","tags":["Collectors"],"description":"Create a new collector for the authenticated client","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectorInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getCollectors","summary":"Get all collectors","tags":["Collectors"],"description":"Get all collectors for the authenticated client with pagination","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectorsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectorsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collectors/{collectorId}":{"get":{"operationId":"getCollector","summary":"Get a specific collector","tags":["Collectors"],"description":"Get details of a specific collector by ID","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectorId","required":true,"description":"Collector UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateCollector","summary":"Update a collector","tags":["Collectors"],"description":"Update a specific collector by ID","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectorInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectorId","required":true,"description":"Collector UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collector"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteCollector","summary":"Delete a collector","tags":["Collectors"],"description":"Delete a specific collector by ID. This will also delete all associated collections.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectorId","required":true,"description":"Collector UUID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/":{"post":{"operationId":"createCollection","summary":"Create a new collection","tags":["Collection Management"],"description":"Create a new collection for organizing trading cards.\n\nA collection is a container for organizing cards, similar to a physical binder or box. Each collection belongs to a specific collector and can be customized with:\n- A descriptive name\n- Type designation (personal, wishlist, for_sale, showcase)\n- Privacy settings (public or private)\n- Optional description\n\n**Use Cases:**\n- Organize cards by theme (e.g., \"1990s Rookies\", \"Hall of Famers\")\n- Track different collection goals (wishlist vs owned)\n- Separate cards for sale from personal collection\n- Create showcases of prized cards\n\n**Important Notes:**\n- Collections are isolated by API key (multi-tenant)\n- Each collector can have multiple collections\n- Collection names must be unique per collector","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getCollections","summary":"List all collections","tags":["Collection Management"],"description":"Retrieve a paginated list of all collections across all collectors for your account.\n\n**Query Parameters:**\n- **page**: Page number (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **collectorId**: Filter by specific collector (optional)\n- **type**: Filter by collection type (personal, wishlist, for_sale, showcase)\n- **isPublic**: Filter by privacy setting (true/false)\n\n**Response includes:**\n- Collection metadata (name, type, privacy, dates)\n- Associated collector information\n- Card count per collection\n- Pagination metadata\n\n**Use Cases:**\n- Display all collections in a dashboard\n- Filter collections by type or collector\n- Implement collection browsing with pagination\n- Generate collection statistics\n\n**Performance Notes:**\n- Results are cached for improved performance\n- Large result sets are automatically paginated\n- Only returns collections owned by your API key","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"collectorId","required":false,"description":"Filter by collector UUID"},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search by collection name (partial match)"},{"schema":{"type":"string","enum":["name"]},"in":"query","name":"sort","required":false,"description":"Field to sort by"},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}":{"get":{"operationId":"getCollection","summary":"Get collection details","tags":["Collection Management"],"description":"Retrieve detailed information about a specific collection.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to retrieve\n\n**Response includes:**\n- Complete collection metadata\n- Collector information\n- Creation and update timestamps\n- Card count statistics\n- Collection type and privacy settings\n\n**Security:**\n- Only collections owned by your API key can be accessed\n- Attempting to access another client's collection returns 404\n\n**Use Cases:**\n- Display collection details page\n- Load collection for editing\n- Verify collection settings\n- Get collection statistics","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateCollection","summary":"Update collection","tags":["Collection Management"],"description":"Update an existing collection's properties.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to update\n\n**Updatable Fields:**\n- **name**: New collection name (must be unique per collector)\n- **description**: Updated description text\n- **type**: Change collection type (personal, wishlist, for_sale, showcase)\n- **isPublic**: Toggle privacy setting\n\n**Important Notes:**\n- Only the collection owner can update it\n- Collection ID and collector cannot be changed\n- Name must remain unique within the collector's collections\n- Changes are immediately reflected in all queries\n\n**Use Cases:**\n- Rename a collection\n- Change collection visibility\n- Update collection purpose (e.g., personal to for_sale)\n- Add or modify description","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteCollection","summary":"Delete collection","tags":["Collection Management"],"description":"Permanently delete a collection and all associated data.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to delete\n\n**⚠️ WARNING:**\n- This action is **irreversible**\n- All cards in the collection will be removed\n- All binders associated with the collection will be deleted\n- Collection statistics and history will be permanently lost\n\n**Security:**\n- Only the collection owner can delete it\n- Returns 404 if collection doesn't exist or belongs to another client\n\n**Response:**\n- 204 No Content on successful deletion\n- No response body is returned\n\n**Use Cases:**\n- Remove obsolete collections\n- Clean up test collections\n- Consolidate multiple collections\n- Account cleanup before deletion","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/breakdown":{"get":{"operationId":"getCollectionBreakdown","summary":"Analyze collection breakdown","tags":["Collection Management"],"description":"Analyze your collection by different dimensions to understand composition and distribution.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to analyze\n\n**Query Parameters:**\n- **groupBy**: Dimension to analyze (release, year, grade, player, manufacturer)\n- **sortBy**: Sort groups by count or percentage (default: count)\n- **order**: Sort order - asc or desc (default: desc)\n- **page**: Page number for pagination (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **minCount**: Filter groups with minimum card count\n\n**Response includes:**\n- **Summary statistics**: Total groups, cards, and top categories\n- **Group breakdowns**: Each group with metrics and top cards\n- **Pagination metadata**: For large result sets\n\n**Analysis Dimensions:**\n- **release**: Group by product release (e.g., \"1989 Topps\", \"2023 Prizm\") to see release concentration\n- **year**: Group by release year to see temporal distribution\n- **grade**: Group by grade to analyze condition distribution\n- **player**: Group by player to see player concentration\n- **manufacturer**: Group by card manufacturer\n\n**Metrics per Group:**\n- Card count and unique card count\n- Total invested (sum of purchase prices)\n- Percentage of total collection\n- Top 5 cards in the group\n\n**Use Cases:**\n- Identify concentration in specific releases or players\n- Analyze grade distribution for grading decisions\n- Discover diversification opportunities\n- Understand collection composition","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","enum":["release","year","grade","player","manufacturer"]},"in":"query","name":"groupBy","required":true,"description":"Dimension to group the collection by"},{"schema":{"default":"count","type":"string","enum":["count","percentage"]},"in":"query","name":"sortBy","required":false,"description":"Metric to sort groups by"},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"},{"schema":{"type":"number","minimum":1},"in":"query","name":"minCount","required":false,"description":"Minimum card count to include in results"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionBreakdownResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionBreakdownResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/analytics":{"get":{"operationId":"getCollectionAnalytics","summary":"Get collection analytics","tags":["Collection Management"],"description":"Retrieve comprehensive analytics about collection composition and purchase data.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to analyze\n\n**Response includes:**\n\n**Overview:**\n- Total cards, unique cards, and quantities\n- Basic collection composition stats\n\n**Financials:**\n- Total invested (sum of all buy prices)\n- Total realized gains (profit/loss from sold cards based on user-entered sale prices)\n\n**Composition:**\n- Graded vs raw card counts and percentages\n- Cards listed for sale\n- Cards already sold\n\n**Use Cases:**\n- Collection overview dashboard\n- Track purchase spending\n- Tax reporting (realized gains from sold cards)\n- Collection composition analysis","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionAnalyticsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionAnalyticsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/set-progress":{"get":{"operationId":"getCollectionSetProgress","summary":"Track set completion progress","tags":["Collection Management"],"description":"Track progress toward completing sets within your collection to focus acquisition efforts.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to analyze\n\n**Query Parameters:**\n- **sortBy**: Sort sets by completion or missing (default: completion)\n- **order**: Sort order - asc or desc (default: desc)\n- **page**: Page number for pagination (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **minCompletion**: Filter sets with minimum completion percentage (0-100)\n- **nearComplete**: Filter for sets >80% complete (boolean)\n\n**Response includes:**\n\n**Summary statistics:**\n- Total sets represented in collection\n- Number of near-complete sets (>80%)\n- Number of fully complete sets (100%)\n\n**Per Set:**\n- Set name, release name, and release year for context\n- Total cards in set vs owned cards\n- Completion percentage\n- Missing card UUIDs (only included for sets >= 85% complete; empty array otherwise)\n\n**Use Cases:**\n- Identify which sets are close to completion\n- Prioritize acquisitions for near-complete sets\n- Track collection completion goals\n\n**Important Notes:**\n- Only base cards are considered (parallels excluded)\n- Missing card UUIDs only returned for sets >= 85% complete (to avoid multi-thousand line responses)\n- For sets < 85% complete, use totalCards - ownedCards to get missing count\n- Sorted by completion percentage (highest first) by default","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"default":"completion","type":"string","enum":["completion","missing","difficulty"]},"in":"query","name":"sortBy","required":false,"description":"Metric to sort sets by"},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"},{"schema":{"type":"number","minimum":0,"maximum":100},"in":"query","name":"minCompletion","required":false,"description":"Filter sets with minimum completion percentage"},{"schema":{"type":"boolean"},"in":"query","name":"nearComplete","required":false,"description":"Filter for sets >80% complete"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProgressListResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProgressListResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/set-progress/{setId}":{"get":{"operationId":"getSetProgress","summary":"Get completion progress for specific set","tags":["Collection Management"],"description":"Get detailed completion progress for a specific set within your collection.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection\n- **setId**: UUID of the set to check progress for\n\n**Response includes:**\n- Set name, release name, and release year\n- Total cards in set vs owned cards\n- Completion percentage (0-100)\n- Array of missing card UUIDs\n\n**Use Cases:**\n- Check progress on a specific set\n- Get list of missing cards for targeted purchasing\n- Track progress toward set completion goal\n- Identify which cards are still needed\n\n**Important Notes:**\n- Only base cards are considered (parallels excluded)\n- Missing cards returned as UUIDs for easy card lookup\n- Returns 404 if set is not represented in collection","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"setId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProgress"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProgress"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/set-progress/{setId}/{parallelId}":{"get":{"operationId":"getParallelSetProgress","summary":"Track parallel completion within a set","tags":["Collection Management"],"description":"Track progress toward completing a specific parallel variant within a set.\n\nThis endpoint tracks completion for a specific parallel (e.g., all Refractors, all Gold parallels) within a set. Unlike the base set progress endpoint which counts any parallel as complete, this endpoint only counts cards where you own the specific parallel variant.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection to analyze\n- **setId**: UUID of the set to check progress for\n- **parallelId**: UUID of the specific parallel variant (e.g., Refractor, Gold, Silver, Prizm, etc.)\n\n**Response includes:**\n- Set name, release name, and release year for context\n- Parallel name (e.g., \"Refractor\", \"Gold Prizm\")\n- Total cards in set vs owned cards of this specific parallel\n- Completion percentage for this parallel variant (0-100)\n- Array of missing card UUIDs for this parallel (for targeted buying)\n\n**How it differs from base set progress:**\n- **Base set progress** (/set-progress/:setId): Counts card #5 as owned if you have ANY parallel (base, refractor, gold, etc.)\n- **Parallel set progress** (this endpoint): Only counts card #5 if you own it as THIS specific parallel\n\n**Use Cases:**\n- Track completion of premium parallel sets (Refractors, numbered parallels)\n- Focus acquisitions on specific parallel variants\n- Chase rare parallel variations (e.g., Gold /10, Orange /25)\n- Set collection goals for parallel variants\n\n**Example Scenario:**\nYou're collecting all Refractor parallels from 2023 Prizm Basketball Base Set. You own 187 of 250 Refractors. This endpoint returns:\n- 74.8% complete\n- List of 63 missing Refractor card UUIDs\n\n**Important Notes:**\n- Only base cards are considered (card variations where baseCardId IS NOT NULL are excluded)\n- Filters collection_cards by the specific parallelId provided\n- Returns 404 if parallel doesn't belong to the specified set\n- Missing cards are returned as UUIDs for easy lookup via the catalog API","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"setId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"parallelId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParallelSetProgress"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParallelSetProgress"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/cards":{"post":{"operationId":"addCollectionCards","summary":"Add cards to collection","tags":["Collection Management"],"description":"Add one or multiple cards to a collection with detailed tracking information.\n\n**Supports two modes:**\n1. **Single Card**: Add one card with all metadata\n2. **Batch Mode**: Add up to 100 cards in a single request\n\n**Card Metadata (all optional):**\n- **quantity**: Number of copies (default: 1)\n- **grade**: Professional grading (e.g., \"PSA 10\", \"BGS 9.5\")\n- **gradeCompany**: Grading service (PSA, BGS, SGC, etc.)\n- **purchasePrice**: What you paid for the card\n- **purchaseDate**: When you acquired it\n- **purchaseFrom**: Where/who you bought it from\n- **condition**: Raw condition if ungraded (Mint, Near Mint, etc.)\n- **notes**: Personal notes about the card\n- **isForSale**: Mark card as available for sale\n- **salePrice**: Asking price if for sale\n\n**Batch Operation:**\n- Use 'cards' array instead of single card fields\n- Mixed success/failure responses possible\n- Returns detailed results for each card\n\n**Use Cases:**\n- Track new acquisitions\n- Import bulk collections\n- Record graded cards\n- Build want lists","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionCardInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCollectionCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getCollectionCards","summary":"List collection cards","tags":["Collection Management"],"description":"Retrieve a paginated list of all cards in a specific collection with advanced filtering options.\n\n**Query Parameters:**\n- **page**: Page number (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **sortBy**: Sort field (name, number, purchaseDate, addedDate)\n- **sortOrder**: asc or desc (default: asc)\n- **search**: Search card names and descriptions\n- **binderId**: Filter by specific binder\n- **graded**: Filter graded cards only (true/false)\n- **forSale**: Filter cards marked for sale\n\n**Response includes:**\n- Full card catalog details (name, set, year, etc.)\n- Collection-specific metadata (quantity, grade, purchase info)\n- Aggregated statistics (card count)\n- Pagination metadata\n\n**Use Cases:**\n- Browse collection inventory\n- Search for specific cards\n- Export collection data\n- Generate collection reports","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cardId","required":false,"description":"Filter by card UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"parallelId","required":false,"description":"Filter by parallel UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"gradeId","required":false,"description":"Filter by grade UUID"},{"schema":{"type":"boolean"},"in":"query","name":"hasSold","required":false,"description":"Filter by sold status (true for sold, false for not sold)"},{"schema":{"type":"string","enum":["buyDate","soldDate","buyPrice","soldPrice"]},"in":"query","name":"sort","required":false,"description":"Field to sort by"},{"schema":{"default":"desc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/cards/{cardId}":{"get":{"operationId":"getCollectionCard","summary":"Get card details","tags":["Collection Management"],"description":"Retrieve complete details for a specific card in a collection.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection\n- **cardId**: UUID of the collection card entry (not the catalog card ID)\n\n**Response includes:**\n- Complete catalog card information\n- All collection-specific metadata\n- Purchase and sale information\n- Grading details if applicable\n- Personal notes\n\n**Use Cases:**\n- View full card details\n- Check card grade and condition\n- Review purchase history\n- Prepare for sale listing","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCard"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCard"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateCollectionCard","summary":"Update card metadata","tags":["Collection Management"],"description":"Update collection-specific metadata for a card.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection\n- **cardId**: UUID of the collection card entry\n\n**Updatable Fields:**\n- **quantity**: Adjust number of copies\n- **grade**: Update or add grading info\n- **gradeCompany**: Change grading service\n- **purchasePrice**: Correct purchase price\n- **purchaseDate**: Fix acquisition date\n- **purchaseFrom**: Update source information\n- **condition**: Change raw condition assessment\n- **notes**: Modify personal notes\n- **isForSale**: Toggle sale status\n- **salePrice**: Update asking price\n- **binderId**: Move to different binder\n\n**Important Notes:**\n- Cannot change the catalog card reference\n- Updates are immediate\n- Previous values are not retained (no history)\n- Only the collection owner can update\n\n**Use Cases:**\n- Update card after grading\n- Adjust quantities after sales\n- Add or modify notes\n- Change sale status","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionCardInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCard"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCard"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteCollectionCard","summary":"Remove card from collection","tags":["Collection Management"],"description":"Permanently remove a card entry from a collection.\n\n**Path Parameters:**\n- **collectionId**: UUID of the collection\n- **cardId**: UUID of the collection card entry to remove\n\n**⚠️ WARNING:**\n- This action is **irreversible**\n- Removes all associated metadata (grade, purchase info, notes)\n- Does not affect the catalog card data\n- If you have multiple copies, this removes ALL of them\n\n**Important Notes:**\n- Only the collection owner can remove cards\n- Returns 204 No Content on success\n- No response body is returned\n\n**Use Cases:**\n- Remove sold cards\n- Clean up duplicate entries\n- Correct mistaken additions\n- Reorganize collections\n\n**Alternative Actions:**\n- To reduce quantity, use PUT to update quantity field\n- To move to another collection, add to new collection first","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/binders":{"post":{"operationId":"createBinder","summary":"Create a binder","tags":["Collection Management"],"description":"Create a new binder within a collection to organize subsets of cards.\n\nA binder is a virtual container for grouping cards, similar to physical card binders or pages. Use binders to:\n- Organize cards by theme or set\n- Create sale lots or trade packages\n- Build showcase presentations\n- Group cards for specific purposes\n\n**Binder Properties:**\n- **name**: Descriptive name (e.g., \"1989 Rookies\", \"For Sale - PSA 10s\")\n- **description**: Optional detailed description\n- **type**: Purpose designation (showcase, for_sale, for_trade, organizing)\n- **sortOrder**: Display order within collection\n- **isPublic**: Visibility setting for sharing\n\n**Important Notes:**\n- Binders belong to a single collection\n- Cards can exist in multiple binders\n- Binder names must be unique within the collection\n- Empty binders are allowed\n\n**Use Cases:**\n- Create themed showcases\n- Organize cards for sale\n- Build trade packages\n- Separate graded from raw cards","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBinderInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getBinders","summary":"List collection binders","tags":["Collection Management"],"description":"Retrieve all binders within a specific collection with pagination and filtering.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n\n**Query Parameters:**\n- **page**: Page number (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **type**: Filter by binder type (showcase, for_sale, for_trade, organizing)\n- **isPublic**: Filter by visibility (true/false)\n- **sortBy**: Sort field (name, createdAt, cardCount, sortOrder)\n- **sortOrder**: asc or desc (default: asc)\n\n**Response includes:**\n- Binder metadata (name, type, description)\n- Card count per binder\n- Creation and update timestamps\n- Pagination metadata\n\n**Use Cases:**\n- Display binder overview\n- Navigate collection structure\n- Find specific binder types\n- Generate binder statistics","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search by binder name (partial match)"},{"schema":{"type":"string","enum":["name"]},"in":"query","name":"sort","required":false,"description":"Field to sort by"},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBindersResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBindersResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/binders/{binderId}":{"get":{"operationId":"getBinder","summary":"Get binder details","tags":["Collection Management"],"description":"Retrieve complete details for a specific binder.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the binder\n\n**Response includes:**\n- Complete binder metadata\n- Card count and list preview\n- Type and visibility settings\n- Timestamps\n\n**Security:**\n- Only accessible to the collection owner\n- Returns 404 if binder doesn't exist or belongs to another client\n\n**Use Cases:**\n- View binder contents\n- Load binder for editing\n- Share binder details\n- Prepare for trade or sale","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateBinder","summary":"Update binder","tags":["Collection Management"],"description":"Update an existing binder's properties.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the binder to update\n\n**Updatable Fields:**\n- **name**: New binder name (must be unique within collection)\n- **description**: Updated description\n- **type**: Change binder type (showcase, for_sale, for_trade, organizing)\n- **isPublic**: Toggle visibility\n- **sortOrder**: Adjust display order\n\n**Important Notes:**\n- Cannot change the parent collection\n- Binder ID remains the same\n- Cards in binder are not affected\n- Name must remain unique\n\n**Use Cases:**\n- Rename binder\n- Change binder purpose\n- Update description\n- Adjust privacy settings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBinderInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Binder"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteBinder","summary":"Delete binder","tags":["Collection Management"],"description":"Permanently delete a binder and remove all card associations.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the binder to delete\n\n**⚠️ WARNING:**\n- This action is **irreversible**\n- All card-to-binder links will be removed\n- Cards remain in the collection (only binder organization is lost)\n- Binder metadata and settings are permanently deleted\n\n**Important Notes:**\n- Does NOT delete the actual cards\n- Cards can still be accessed through the collection\n- Other binders are not affected\n\n**Use Cases:**\n- Remove obsolete binders\n- Clean up organization\n- Delete test binders\n- Consolidate binders","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/binders/{binderId}/cards":{"post":{"operationId":"addCardToBinder","summary":"Add card to binder","tags":["Collection Management"],"description":"Add an existing collection card to a binder for organization.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the target binder\n\n**Request Body:**\n- **collectionCardId**: UUID of the collection card to add\n- **sortOrder**: Optional display order within binder\n- **notes**: Optional binder-specific notes\n\n**Important Notes:**\n- Card must already exist in the collection\n- Same card can be in multiple binders\n- Does not duplicate the card, just creates a link\n- Original card metadata is preserved\n\n**Use Cases:**\n- Organize cards into themed binders\n- Create sale or trade lots\n- Build showcases\n- Group cards for specific purposes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCardToBinderInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BinderCard"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getBinderCards","summary":"List binder cards","tags":["Collection Management"],"description":"Retrieve all cards organized within a specific binder.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the binder\n\n**Query Parameters:**\n- **page**: Page number (default: 1)\n- **limit**: Items per page (default: 20, max: 100)\n- **sortBy**: Sort field (name, number, sortOrder)\n- **sortOrder**: asc or desc (default: asc)\n- **search**: Search card names\n\n**Response includes:**\n- Full card details from catalog\n- Collection-specific metadata\n- Binder-specific sort order\n- Pagination metadata\n\n**Use Cases:**\n- View binder contents\n- Generate binder listings\n- Export binder inventory","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBinderCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBinderCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/binders/{binderId}/cards/{cardId}":{"delete":{"operationId":"removeCardFromBinder","summary":"Remove card from binder","tags":["Collection Management"],"description":"Remove a card's association with a binder without deleting it from the collection.\n\n**Path Parameters:**\n- **collectionId**: UUID of the parent collection\n- **binderId**: UUID of the binder\n- **cardId**: UUID of the binder-card association\n\n**Important Notes:**\n- Only removes the binder link, not the card itself\n- Card remains in the collection\n- Card can still be in other binders\n- This is reversible (card can be re-added)\n\n**Use Cases:**\n- Reorganize binder contents\n- Remove sold cards from sale binder\n- Clean up binder organization\n- Move cards between binders\n\n**Response:**\n- 204 No Content on success\n- No response body","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"binderId","required":true,"description":"Binder UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Binder Card UUID (the link ID, not the collection card ID)"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/cards/{cardId}/image":{"post":{"operationId":"uploadCollectionCardImage","summary":"Upload collection card image","tags":["Collection Card Images"],"description":"Upload a photo of a card in your collection. Maximum file size: 2MB. Accepts JPEG, PNG, WebP, and HEIC formats.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadCollectionCardImageResponse"}}}}}},"get":{"operationId":"getCollectionCardImage","summary":"Get collection card image","tags":["Collection Card Images"],"description":"Retrieve the full-resolution image added for the specified card within the collection.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"responses":{"200":{"description":"Binary image data. Response Content-Type is either image/jpeg (most segments) or image/png (segments like Pokemon that need transparency).","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/collection/{collectionId}/cards/{cardId}/image/thumb":{"get":{"operationId":"getCollectionCardImageThumbnail","summary":"Get collection card image thumbnail","tags":["Collection Card Images"],"description":"Retrieve the thumbnail image added for the specified card within the collection.","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"collectionId","required":true,"description":"Collection UUID"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"cardId","required":true,"description":"Collection Card UUID"}],"responses":{"200":{"description":"Binary image data. Response Content-Type is either image/jpeg (most segments) or image/png (segments like Pokemon that need transparency).","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/lists/":{"post":{"operationId":"createList","summary":"Create a new list","tags":["Lists"],"description":"Create a new list of cards (want list, collection goals, etc.)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateListInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getLists","summary":"Get all lists","tags":["Lists"],"description":"Get all lists for the authenticated client with pagination","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"query","name":"collectorId","required":false,"description":"Filter by collector UUID"},{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Search by list name (partial match)"},{"schema":{"type":"string","enum":["name"]},"in":"query","name":"sort","required":false,"description":"Field to sort by"},{"schema":{"default":"asc","type":"string","enum":["asc","desc"]},"in":"query","name":"order","required":false,"description":"Sort order"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/lists/{listId}":{"get":{"operationId":"getList","summary":"Get a specific list","tags":["Lists"],"description":"Get details of a specific list by ID","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateList","summary":"Update a list","tags":["Lists"],"description":"Update a specific list by ID","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateListInput"}}}},"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteList","summary":"Delete a list","tags":["Lists"],"description":"Delete a specific list by ID. This will also remove all card associations.","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/lists/{listId}/cards":{"post":{"operationId":"addCardsToList","summary":"Add card(s) to a list","tags":["Lists"],"description":"Add one or multiple cards to a specific list. Supports both single card and batch (up to 100 cards) operations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCardToListInput"}}}},"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCardsToListResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getListCards","summary":"Get all cards in a list","tags":["Lists"],"description":"Get all cards in a specific list with pagination","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListCardsResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListCardsResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/lists/{listId}/cards/{cardId}":{"delete":{"operationId":"removeCardFromList","summary":"Remove a card from a list","tags":["Lists"],"description":"Remove a specific card from a list","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"listId","required":true,"description":"List UUID"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"cardId","required":true,"description":"Card UUID to remove from list"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/images/cards/{id}":{"get":{"operationId":"getCardImage","summary":"Get card image","tags":["Images"],"description":"Retrieve a card image by ID. Returns either raw JPEG (format=raw) or JSON with base64 data (format=json).","parameters":[{"schema":{"default":"raw","type":"string","enum":["raw","json"]},"in":"query","name":"format","required":false,"description":"Image response format: \"raw\" returns binary image data, \"json\" returns base64-encoded data URI"},{"schema":{"default":"false","type":"string","enum":["true","false"]},"in":"query","name":"default","required":false,"description":"When true, returns a default placeholder image if the card image is not available. When false (default), returns 404 if no image exists."},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"Unique identifier (UUID) of the card to retrieve the image for"}],"responses":{"200":{"description":"Card image in requested format. When format=raw (default), returns binary image data with Content-Type image/jpeg or image/png depending on the card. When format=json, returns JSON with a base64 data URI (prefix reflects the actual format).","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageJsonResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/ai/query":{"post":{"operationId":"processAIQuery","summary":"Process a natural language query","tags":["AI"],"description":"Submit a plaintext natural language question via REST API and receive an AI-generated response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIQueryRequestInput"}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIQueryResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIError"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIError"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIError"}}}}}}},"/v1/feedback/release/{id}":{"post":{"operationId":"submitReleaseFeedback","summary":"Submit feedback for a release","tags":["Feedback"],"description":"Submit feedback for a specific release in the CardSight catalog.\n\nUse this endpoint to report:\n- Incorrect release information (name, year, manufacturer)\n- Missing or incorrect release metadata\n- Data quality issues with the release\n- General suggestions for improvement\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/set/{id}":{"post":{"operationId":"submitSetFeedback","summary":"Submit feedback for a set","tags":["Feedback"],"description":"Submit feedback for a specific set within a release.\n\nUse this endpoint to report:\n- Incorrect set information (name, card count, subset designation)\n- Missing or duplicate sets\n- Incorrect set ordering or numbering\n- Data quality issues specific to the set\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/card/{id}":{"post":{"operationId":"submitCardFeedback","summary":"Submit feedback for a card","tags":["Feedback"],"description":"Submit feedback for a specific card in the catalog.\n\nUse this endpoint to report:\n- Incorrect player name or card details\n- Wrong card number or designation\n- Missing or incorrect parallel/variant information\n- Incorrect card attributes (rookie card, autograph, memorabilia)\n- Image quality issues or wrong image\n- Pricing discrepancies\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/manufacturer/{id}":{"post":{"operationId":"submitManufacturerFeedback","summary":"Submit feedback for a manufacturer","tags":["Feedback"],"description":"Submit feedback for a specific card manufacturer.\n\nUse this endpoint to report:\n- Incorrect manufacturer name or branding\n- Missing manufacturer information\n- Manufacturer relationship issues\n- Historical inaccuracies about the manufacturer\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/segment/{id}":{"post":{"operationId":"submitSegmentFeedback","summary":"Submit feedback for a segment","tags":["Feedback"],"description":"Submit feedback for a specific market segment (e.g., Baseball, Football, Basketball).\n\nUse this endpoint to report:\n- Incorrect segment categorization\n- Missing segment information\n- Segment metadata issues\n- General suggestions for segment organization\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/identify/{id}":{"post":{"operationId":"submitIdentifyFeedback","summary":"Submit feedback for card identification","tags":["Feedback"],"description":"Submit feedback for a card identification result from the AI identification service.\n\nUse this endpoint to report:\n- Incorrect card identification from uploaded image\n- Wrong player or card details identified\n- Misidentified year, set, or manufacturer\n- AI confidence score issues\n- Suggestions to improve identification accuracy\n\nThis feedback helps improve our AI card identification model.\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message for the same entity within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/general":{"post":{"operationId":"submitGeneralFeedback","summary":"Submit general feedback","tags":["Feedback"],"description":"Submit general feedback about the CardSight API or catalog that is not specific to any particular entity.\n\nUse this endpoint for:\n- API feature requests or suggestions\n- General data quality observations\n- Platform-wide issues or improvements\n- User experience feedback\n- Documentation or integration feedback\n- Business inquiries or partnerships\n\nUnlike other feedback endpoints, this does not require an entity ID.\n\n**Rate Limiting**: Maximum 50 feedback submissions per day per API key\n**Duplicate Detection**: Same feedback message within 1 hour will be rejected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackInputInput"}}}},"security":[{"apiKey":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/{id}":{"get":{"operationId":"getFeedback","summary":"Retrieve feedback by ID","tags":["Feedback"],"description":"Retrieve a previously submitted feedback entry by its unique ID.\n\n**Important Security Notes:**\n- You can only retrieve feedback submitted by your own API key\n- Attempting to access feedback from another client will result in a 403 Forbidden error\n- The unique ID is a UUID that was returned when the feedback was originally submitted\n\nUse this endpoint to:\n- Check the status of your submitted feedback\n- Retrieve details of feedback for your own records\n- Verify that feedback was successfully submitted\n\n**Response Codes:**\n- 200: Feedback found and belongs to your client\n- 401: Authentication required\n- 403: Feedback exists but belongs to another client\n- 404: Feedback ID not found","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true,"description":"The unique ID (UUID) of the entity this feedback relates to"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/subscription/":{"get":{"operationId":"getSubscription","summary":"Get subscription information","tags":["Subscription"],"description":"Retrieve subscription usage information for the authenticated client.\n\n**Returns:**\n- Total aggregate API calls made across all API keys for the current billing period\n- Array containing usage information for the current API key being used to make this request\n\n**Billing Period:**\n- The billing period is calculated monthly (first day of the current month to present)\n- Usage data is tracked in the api_key_usage_monthly table\n- Calls are aggregated across all API keys belonging to the client\n\n**Response Fields:**\n- `calls`: Total number of API calls across all your API keys for the current billing period\n- `api_keys`: Array with one element showing the current API key and its usage\n  - `key`: The API key used to make this request\n  - `calls`: Number of API calls made using this specific key for the current billing period\n\n**Example Response:**\n```json\n{\n  \"calls\": 1250,\n  \"api_keys\": [\n    {\n      \"key\": \"csa_live_abc123...\",\n      \"calls\": 450\n    }\n  ]\n}\n```\n\n**Use Cases:**\n- Monitor your API usage to stay within subscription limits\n- Track usage by individual API key\n- Identify which keys are making the most requests\n- Billing and cost tracking","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionInfo"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/grades/companies":{"get":{"operationId":"getGradingCompanies","summary":"List all grading companies","tags":["Grades"],"description":"Retrieve a complete list of all grading companies available in the system.\n\n**Grading companies** are organizations that authenticate and grade trading cards, such as PSA, BGS (Beckett), SGC, and CGC.\n\n**Response includes:**\n- List of all grading companies with metadata\n- Company names, descriptions, and notes\n- Total count of companies\n\n**Use Cases:**\n- Display grading company selection in UI\n- Populate dropdown menus for grading filters\n- Show available grading options to users\n- Reference data for collection management\n\n**Example Companies:**\n- PSA (Professional Sports Authenticator)\n- BGS (Beckett Grading Services)\n- SGC (Sportscard Guaranty)\n- CGC (Certified Guaranty Company)\n\n**Important Notes:**\n- This endpoint returns all companies in the system\n- Companies are sorted alphabetically by name\n- No authentication required (public reference data)","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradingCompaniesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradingCompaniesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/grades/companies/{companyId}/types":{"get":{"operationId":"getGradingTypes","summary":"Get grading types for a company","tags":["Grades"],"description":"Retrieve all grading types offered by a specific grading company.\n\n**Grading types** represent different grading services offered by a company, such as:\n- PSA: Regular, Crossover, Dual Grade\n- BGS: Standard, Black Label, Pristine\n- SGC: Regular, Tuxedo, Premium\n\n**Path Parameters:**\n- **companyId**: UUID of the grading company\n\n**Response includes:**\n- List of all grading types for the company\n- Type names, descriptions, and notes\n- Parent grading company information for context\n- Total count of types\n\n**Use Cases:**\n- Display available grading services for a company\n- Filter grades by grading type\n- Show grading options when adding cards to collection\n- Populate grading type selection in UI\n\n**Example Types:**\n- PSA Regular (standard PSA grading)\n- BGS Black Label (perfect 10 across all subgrades)\n- SGC Tuxedo (premium black label holder)\n\n**Important Notes:**\n- Types are specific to each grading company\n- Returns 404 if company ID doesn't exist\n- Types are sorted alphabetically by name","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"companyId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradingTypesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradingTypesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/grades/companies/{companyId}/types/{typeId}/grades":{"get":{"operationId":"getGrades","summary":"Get grades for a grading type","tags":["Grades"],"description":"Retrieve all specific grades available for a grading type.\n\n**Grades** are the actual numeric/letter grades assigned to cards, such as:\n- PSA: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10\n- BGS: 1, 1.5, 2, 2.5, ... 9, 9.5, 10\n- SGC: 1, 1.5, 2, 2.5, ... 9, 9.5, 10\n\n**Path Parameters:**\n- **companyId**: UUID of the grading company\n- **typeId**: UUID of the grading type\n\n**Response includes:**\n- List of all grades for the grading type\n- Grade values (as strings to support decimals like \"9.5\")\n- Parent grading type and company information for context\n- Total count of grades\n\n**Use Cases:**\n- Display available grades when adding graded cards to collection\n- Filter collection cards by specific grade\n- Show grade options in grading selection UI\n- Validate grade values for card submissions\n\n**Example Grades:**\n- PSA 10 (Gem Mint)\n- PSA 9 (Mint)\n- BGS 9.5 (Gem Mint)\n- SGC 10 (Pristine)\n\n**Important Notes:**\n- Grades are specific to each grading type\n- Grade values are stored as strings to support decimal grades\n- Returns 404 if company or type ID doesn't exist\n- Validates that the type belongs to the specified company\n- Grades are sorted by their grade value","parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"companyId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"typeId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradesResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GradesResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/pricing/{card_id}":{"get":{"operationId":"getCardPricing","summary":"Get completed sales pricing for a card","tags":["Pricing"],"description":"Returns completed sales data for a single card, grouped into raw (ungraded) and graded sections. Graded results are organized by grading company and grade value. Supports filtering by parallel variant, grade, time period, and listing type.","parameters":[{"schema":{"type":"string"},"in":"query","name":"parallel_id","required":false,"description":"Filter by parallel variant. Pass a UUID for a specific parallel, \"null\" for base card only, or omit for all variants."},{"schema":{"type":"string"},"in":"query","name":"grade_id","required":false,"description":"Filter by grade. Pass a UUID for a specific grade, \"null\" for ungraded only, or omit for all grades."},{"schema":{"default":"all","type":"string"},"in":"query","name":"period","required":false,"description":"Lookback period. Examples: \"7d\", \"14d\", \"2w\", \"3m\", \"1y\", \"all\". Omit or \"all\" for no time limit."},{"schema":{"default":"both","type":"string","enum":["auction","fixed","both"]},"in":"query","name":"listing_type","required":false,"description":"Filter by listing type. auction=completed auctions, fixed=buy-it-now, both=all"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":500},"in":"query","name":"limit","required":false,"description":"Maximum number of records to return per card"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"card_id","required":true,"description":"Card UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/pricing/":{"post":{"operationId":"getBulkPricing","summary":"Get pricing for multiple cards","tags":["Pricing"],"description":"Returns completed sales data for up to 100 cards in a single request. Each card is processed independently — individual cards may succeed or fail without affecting others. Results include the same raw/graded grouping as the single-card endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPricingRequestInput"}}}},"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPricingResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPricingResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/marketplace/{card_id}":{"get":{"operationId":"getCardMarketplace","summary":"Get active marketplace listings for a card","tags":["Marketplace"],"description":"Returns currently active marketplace listings for a single card, grouped into raw (ungraded) and graded sections. Includes a marketplace search link as the last record in the raw section. Supports filtering by parallel variant, grade, and listing type.","parameters":[{"schema":{"type":"string"},"in":"query","name":"parallel_id","required":false,"description":"Filter by parallel variant. Pass a UUID for a specific parallel, \"null\" for base card only, or omit for all variants."},{"schema":{"type":"string"},"in":"query","name":"grade_id","required":false,"description":"Filter by grade. Pass a UUID for a specific grade, \"null\" for ungraded only, or omit for all grades."},{"schema":{"default":"both","type":"string","enum":["auction","fixed","both"]},"in":"query","name":"listing_type","required":false,"description":"Filter by listing type. auction=auctions, fixed=buy-it-now, both=all"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":500},"in":"query","name":"limit","required":false,"description":"Maximum number of records to return per card"},{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"in":"path","name":"card_id","required":true,"description":"Card UUID"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/release-calendar/":{"get":{"operationId":"getReleaseCalendar","summary":"List release calendar entries","tags":["Release Calendar"],"description":"Retrieve a paginated list of upcoming and recent card product releases. Each entry includes the release name, year, release date, pre-order date, and associated segment and manufacturer identifiers. Results are sorted by release date (newest first). Filter by segment, manufacturer, or year to narrow results.","parameters":[{"schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100},"in":"query","name":"take","required":false,"description":"Number of items to return per page. Minimum: 1, Maximum: 100, Default: 20. Use larger values for bulk data retrieval, smaller for responsive UIs."},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false,"description":"Number of items to skip (offset). Default: 0. Use for pagination: page 2 with take=20 would use skip=20, page 3 would use skip=40, etc."},{"schema":{"type":"string"},"in":"query","name":"segment","required":false,"description":"Filter by segment. Accepts a UUID or segment name (case-insensitive)."},{"schema":{"type":"string"},"in":"query","name":"manufacturer","required":false,"description":"Filter by manufacturer. Accepts a UUID or manufacturer name (case-insensitive)."},{"schema":{"type":"string"},"in":"query","name":"year","required":false,"description":"Filter by exact release year (e.g., \"2026\")."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReleaseCalendarResponse"}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReleaseCalendarResponse"}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"servers":[{"url":"https://api.cardsight.ai","description":"CardSight AI API"}],"security":[{"apiKey":[]}],"tags":[{"name":"Card Detection","description":"Detect trading card presence in images (Free)"},{"name":"Card Identification","description":"AI-powered card identification from images"},{"name":"Catalog","description":"Browse and search the card catalog"},{"name":"Collection Management","description":"Manage card collections and inventory (Free)"},{"name":"Collectors","description":"Collector profile management (Free)"},{"name":"Lists","description":"Create and manage card want/trade lists (Free)"},{"name":"Pricing","description":"Card pricing history and completed sales data"},{"name":"Marketplace","description":"Active marketplace listings for cards"},{"name":"Grades","description":"Grading company and population data (Free)"},{"name":"Autocomplete","description":"Search suggestions for catalog fields (Free)"},{"name":"Feedback","description":"Submit feedback and corrections (Free)"},{"name":"Subscription","description":"API subscription and usage information (Free)"},{"name":"Health","description":"Service health and status checks (Free)"}]}