{"openapi":"3.1.0","info":{"title":"MTG Collection API","description":"Local SQLite collection and deck tools for humans and agents. Collection entries identify printings; deck entries use oracle_id to aggregate equivalent printings. No AI provider or API key required.","version":"1.0.0"},"paths":{"/api/health":{"get":{"tags":["System"],"summary":"Health","operationId":"health_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/settings":{"get":{"tags":["System"],"summary":"Get Settings","operationId":"get_settings_api_settings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"tags":["System"],"summary":"Put Settings","operationId":"put_settings_api_settings_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/formats":{"get":{"tags":["Cards"],"summary":"Formats","operationId":"formats_api_formats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/collection":{"get":{"tags":["Cards"],"summary":"Search Collection","description":"Search owned cards by default. include_unowned=true adds cached unowned references for draft planning; available_only=true still excludes zero free copies. assigned_quantity counts active decks only. Drafts never claim ownership or reserve copies. deck_id excludes that active deck's reservation when editing. Colors uses WUBRG or C; identity=true uses Commander identity. q searches English/Spanish names, rules, types and keywords.","operationId":"search_collection_api_collection_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"colors","in":"query","required":false,"schema":{"type":"string","default":"","title":"Colors"}},{"name":"color_mode","in":"query","required":false,"schema":{"enum":["contains","subset","exact"],"type":"string","default":"contains","title":"Color Mode"}},{"name":"identity","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Identity"}},{"name":"card_type","in":"query","required":false,"schema":{"type":"string","default":"","title":"Card Type"}},{"name":"rarity","in":"query","required":false,"schema":{"type":"string","default":"","title":"Rarity"}},{"name":"set_code","in":"query","required":false,"schema":{"type":"string","default":"","title":"Set Code"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","default":"","title":"Tag"}},{"name":"keyword","in":"query","required":false,"schema":{"type":"string","default":"","title":"Keyword"}},{"name":"ability_type","in":"query","required":false,"schema":{"type":"string","default":"","title":"Ability Type"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"","title":"Format"}},{"name":"max_mana","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Max Mana"}},{"name":"group","in":"query","required":false,"schema":{"enum":["printing","oracle"],"type":"string","default":"printing","title":"Group"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["name","mana","quantity","set"],"type":"string","default":"name","title":"Sort"}},{"name":"available_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Available Only"}},{"name":"include_unowned","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Unowned"}},{"name":"deck_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deck Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/catalog/search":{"get":{"tags":["Cards"],"summary":"Catalog Search","description":"Online English/Spanish name lookup for manual additions. Preview only; does not change ownership or cache cards. Select a printing and use import preview/commit to add copies.","operationId":"catalog_search_api_catalog_search_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Name"}},{"name":"set_code","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9]{0,10}$","default":"","title":"Set Code"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cards/{card_id}":{"get":{"tags":["Cards"],"summary":"Get Card","operationId":"get_card_api_cards__card_id__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keywords":{"get":{"tags":["Cards"],"summary":"Keyword Glossary","description":"Offline plain-language explanations, classifications, and official rule references. Included in every card detail under keyword_explanations.","operationId":"keyword_glossary_api_keywords_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keywords/{name}":{"get":{"tags":["Cards"],"summary":"Keyword Explanation","operationId":"keyword_explanation_api_keywords__name__get","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cards/{card_id}/image/{face_index}":{"get":{"tags":["Cards"],"summary":"Card Image","operationId":"card_image_api_cards__card_id__image__face_index__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}},{"name":"face_index","in":"path","required":true,"schema":{"type":"integer","title":"Face Index"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/enrichment":{"get":{"tags":["System"],"summary":"Enrichment Status","operationId":"enrichment_status_api_enrichment_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["System"],"summary":"Start Enrichment","description":"Download missing card images, expansion metadata, and rulings into SQLite. Poll GET /api/enrichment for progress. Retry only missing resources after failures.","operationId":"start_enrichment_api_enrichment_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/collection/{card_id}":{"patch":{"tags":["Cards"],"summary":"Update Quantity","operationId":"update_quantity_api_collection__card_id__patch","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quantity"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Cards"],"summary":"Remove Card","description":"Remove this printing from active ownership, preserving metadata/images. Saved deck reservations must remain covered by other owned printings.","operationId":"remove_card_api_collection__card_id__delete","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/stats":{"get":{"tags":["Cards"],"summary":"Stats","operationId":"stats_api_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/facets":{"get":{"tags":["Cards"],"summary":"Facets","operationId":"facets_api_facets_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/imports/preview":{"post":{"tags":["Imports"],"summary":"Preview Import","description":"Resolve every line through cached data / exact Scryfall lookups. Does not change owned quantities. Any error blocks the entire commit. Repeated lines are summed.","operationId":"preview_import_api_imports_preview_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/imports/{import_id}/commit":{"post":{"tags":["Imports"],"summary":"Commit Import","description":"Atomically apply a preview. Add is for new acquisitions; replace is a complete inventory snapshot. Repeated identical lists require allow_duplicate=true.","operationId":"commit_import_api_imports__import_id__commit_post","parameters":[{"name":"import_id","in":"path","required":true,"schema":{"type":"string","title":"Import Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitInput"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/imports":{"get":{"tags":["Imports"],"summary":"Import History","operationId":"import_history_api_imports_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/cards/refresh":{"post":{"tags":["Cards"],"summary":"Refresh Metadata","description":"Explicitly update cached rules and legality for every known printing; ownership and decks remain unchanged.","operationId":"refresh_metadata_api_cards_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/decks":{"get":{"tags":["Decks"],"summary":"List Decks","operationId":"list_decks_api_decks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["Decks"],"summary":"Create Deck","operationId":"create_deck_api_decks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeckInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/basic-lands":{"get":{"tags":["Decks"],"summary":"Basic Land Supply","description":"Unlimited basic-land references for deck building, separate from owned quantities. Missing reference metadata is fetched once from Scryfall.","operationId":"basic_land_supply_api_basic_lands_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/decks/{deck_id}":{"get":{"tags":["Decks"],"summary":"Get Deck","operationId":"get_deck_api_decks__deck_id__get","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Decks"],"summary":"Put Deck","operationId":"put_deck_api_decks__deck_id__put","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeckInput"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Decks"],"summary":"Delete Deck","operationId":"delete_deck_api_decks__deck_id__delete","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/decks/{deck_id}/conversion/preview":{"post":{"tags":["Decks"],"summary":"Preview Conversion","description":"Read the proposed card replacements and shortages, reusing copies reserved by the active base version. No decks or ownership change.","operationId":"preview_conversion_api_decks__deck_id__conversion_preview_post","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionPreview"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/decks/{deck_id}/conversion/confirm":{"post":{"tags":["Decks"],"summary":"Confirm Conversion","description":"After review and explicit confirmation, atomically make the target Active and the old version Draft. A changed preview must be reviewed again.","operationId":"confirm_conversion_api_decks__deck_id__conversion_confirm_post","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionConfirmation"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/decks/validate":{"post":{"tags":["Decks"],"summary":"Validate Deck","operationId":"validate_deck_api_decks_validate_post","parameters":[{"name":"deck_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deck Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeckInput"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/decks/{deck_id}/export":{"get":{"tags":["Decks"],"summary":"Export Deck","operationId":"export_deck_api_decks__deck_id__export_get","parameters":[{"name":"deck_id","in":"path","required":true,"schema":{"type":"string","title":"Deck Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/collection/export.csv":{"get":{"tags":["Exports"],"summary":"Export Collection","operationId":"export_collection_api_collection_export_csv_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/backups":{"post":{"tags":["Exports"],"summary":"Backup","description":"Create a consistent local SQLite snapshot (including quantities, import history, and decks).","operationId":"backup_api_backups_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/collection/export.json":{"get":{"tags":["Exports"],"summary":"Export Metadata","description":"Export every owned printing's complete metadata. Images remain in the SQLite backup and are linked by local URLs.","operationId":"export_metadata_api_collection_export_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/backups/{filename}":{"get":{"tags":["Exports"],"summary":"Download Backup","operationId":"download_backup_api_backups__filename__get","parameters":[{"name":"filename","in":"path","required":true,"schema":{"type":"string","title":"Filename"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/agent/context":{"get":{"tags":["Agent"],"summary":"Agent Context","description":"Discover collection tools and constraints before producing future recommendations. This endpoint does not make suggestions.","operationId":"agent_context_api_agent_context_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"CommitInput":{"properties":{"allow_duplicate":{"type":"boolean","title":"Allow Duplicate","default":false}},"type":"object","title":"CommitInput"},"ConversionConfirmation":{"properties":{"source_deck_id":{"type":"string","title":"Source Deck Id"},"confirmation_token":{"type":"string","maxLength":64,"minLength":64,"title":"Confirmation Token"},"confirmed":{"type":"boolean","const":true,"title":"Confirmed"}},"type":"object","required":["source_deck_id","confirmation_token","confirmed"],"title":"ConversionConfirmation"},"ConversionPreview":{"properties":{"source_deck_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Deck Id"}},"type":"object","title":"ConversionPreview"},"DeckEntry":{"properties":{"oracle_id":{"type":"string","maxLength":100,"minLength":1,"title":"Oracle Id"},"zone":{"type":"string","enum":["main","sideboard","commander"],"title":"Zone","default":"main"},"quantity":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Quantity"},"source":{"type":"string","enum":["collection","basic_land_supply"],"title":"Source","default":"collection"}},"type":"object","required":["oracle_id","quantity"],"title":"DeckEntry"},"DeckInput":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"format":{"type":"string","title":"Format","default":"casual"},"status":{"type":"string","enum":["active","draft"],"title":"Status","default":"active"},"parent_deck_id":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Parent Deck Id"},"strategy":{"type":"string","maxLength":2000,"title":"Strategy","default":""},"notes":{"type":"string","maxLength":10000,"title":"Notes","default":""},"cards":{"items":{"$ref":"#/components/schemas/DeckEntry"},"type":"array","maxItems":1000,"title":"Cards"}},"type":"object","required":["name"],"title":"DeckInput"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImportInput":{"properties":{"text":{"type":"string","maxLength":1000000,"title":"Text"},"filename":{"type":"string","maxLength":300,"title":"Filename","default":"pasted-list.txt"},"mode":{"type":"string","enum":["add","replace"],"title":"Mode","default":"add"}},"type":"object","required":["text"],"title":"ImportInput"},"Quantity":{"properties":{"quantity":{"type":"integer","maximum":100000.0,"minimum":0.0,"title":"Quantity"}},"type":"object","required":["quantity"],"title":"Quantity"},"Settings":{"properties":{"reserve_cards":{"type":"boolean","title":"Reserve Cards"},"import_mode":{"type":"string","enum":["add","replace"],"title":"Import Mode","default":"add"}},"type":"object","required":["reserve_cards"],"title":"Settings"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}