{ "openapi": "3.1.1", "info": { "title": "DivorceDads.Api.Host | v1", "version": "1.0.0" }, "servers": [ { "url": "http://api.divorceddadstcgfan.com/" } ], "paths": { "/api/v1/artists": { "get": { "tags": [ "Catalog" ], "summary": "List active artists ordered by name.", "operationId": "GetArtists", "responses": { "200": { "description": "OK" } } } }, "/api/v1/artists/{id}": { "get": { "tags": [ "Catalog" ], "summary": "Get one active artist.", "operationId": "GetArtist", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/cards/export": { "get": { "tags": [ "Catalog" ], "summary": "Materialize a complete deterministic checklist (maximum 2,000 rows and 2 MiB).", "description": "Uses the same q, resultUnit, sort and direction as search. Page/pageSize are ignored. Uncached, bounded consistent read; random searches return 400. Limits return 422 without partial data; capacity returns 429 and read timeout returns 503.", "operationId": "ExportCards", "parameters": [ { "name": "q", "in": "query", "description": "Card query. Exact number filters use the ordinary base or {base}-S for serialized printings; lowercase s is accepted. Quantity is separate; old quantity-suffix numbers are not accepted.", "schema": { "type": "string" }, "example": "number:279-S" }, { "name": "random", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "sort", "in": "query", "description": "Sort results by name or numeric-aware card number. Defaults to name.", "schema": { "type": "string" }, "example": "cardNumber" }, { "name": "direction", "in": "query", "description": "Sort in ascending or descending order. Defaults to ascending.", "schema": { "type": "string" }, "example": "asc" }, { "name": "resultUnit", "in": "query", "description": "Result unit: cards (default, one preferred Printing per Card) or printings (all matching Printings). TotalCount and random sampling use this unit. Case-insensitive; empty, unknown or repeated values return invalid_result_unit.", "schema": { "enum": [ "cards", "printings" ], "type": "string", "default": "cards" }, "example": "printings" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResultOfCardSummaryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/cards": { "get": { "tags": [ "Catalog" ], "summary": "Search Cards or individual Printings by name or numeric-aware card number. Use random=true without sort parameters for a random sample.", "description": "resultUnit=cards (default) returns one row per canonical Card; resultUnit=printings returns every matching active Printing. Values are case-insensitive; empty, unknown or repeated units return 400 (invalid_result_unit). Example: ?q=name:Beerium&resultUnit=printings. TotalCount counts the selected unit; PrintingCount always includes all active sibling printings. Printing filters apply to the same returned Printing. Card text matches gameplay or flavor text on any active sibling, which need not be the returned Printing. Grouped representatives prefer newest known Product release date (unknown last), then Standard availability (including Standard + Holographic), Holographic and Serialized Holographic for equal dates, then Printing ID descending. Missing images do not change selection. Name sorting in printing mode groups by name/Card ID, then ascending numeric Printing order; cardNumber sorting uses the numeric tuple in the requested direction. Random samples the selected unit, may include multiple Printings of a Card, reports page 1 and is non-cacheable. Defaults page=1, pageSize=20 (clamped 1..100); excessive offsets return invalid_pagination. Pages are live reads, not snapshots. Exact printing detail is unaffected.", "operationId": "SearchCards", "parameters": [ { "name": "q", "in": "query", "description": "Card query. Exact number filters use the ordinary base or {base}-S for serialized printings; lowercase s is accepted. Quantity is separate; old quantity-suffix numbers are not accepted.", "schema": { "type": "string" }, "example": "number:279-S" }, { "name": "random", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "sort", "in": "query", "description": "Sort results by name or numeric-aware card number. Defaults to name.", "schema": { "type": "string" }, "example": "cardNumber" }, { "name": "direction", "in": "query", "description": "Sort in ascending or descending order. Defaults to ascending.", "schema": { "type": "string" }, "example": "asc" }, { "name": "resultUnit", "in": "query", "description": "Result unit: cards (default, one preferred Printing per Card) or printings (all matching Printings). TotalCount and random sampling use this unit. Case-insensitive; empty, unknown or repeated values return invalid_result_unit.", "schema": { "enum": [ "cards", "printings" ], "type": "string", "default": "cards" }, "example": "printings" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResultOfCardSummaryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/cards/syntax": { "get": { "tags": [ "Catalog" ], "summary": "Describe the supported card search operators, fields, and examples.", "operationId": "GetCardSyntax", "responses": { "200": { "description": "OK" } } } }, "/api/v1/cards/by-number/{cardNumber}": { "get": { "tags": [ "Catalog" ], "summary": "Get one active printing by its globally unique full card number; GUID lookup remains available.", "description": "Use the ordinary positive base number or {base}-S (for example 279-S). Lowercase s is normalized. Archived printings, Cards, Products and Sets are excluded. Legacy quantity suffixes return 400.", "operationId": "GetPrintingByNumber", "parameters": [ { "name": "cardNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailDto" } } } }, "404": { "description": "Not Found" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/cards/url-identities": { "get": { "tags": [ "Catalog" ], "summary": "Enumerate active numbered printing IDs, numbers and names in bounded pages ordered by printing ID for URL generation.", "description": "Defaults: page=1, pageSize=100; maximum pageSize=100. Returns items, page, pageSize and totalCount without per-printing detail requests. Excludes unnumbered and archived resources. Pages are live reads, not a cross-request snapshot; regenerate after catalog changes. The web layer owns name slugs and public URLs.", "operationId": "GetPrintingUrlIdentities", "parameters": [ { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResultOfPrintingUrlIdentityDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/cards/{id}": { "get": { "tags": [ "Catalog" ], "summary": "Get a single printing with canonical gameplay data and sibling printings.", "operationId": "GetPrinting", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/sets": { "get": { "tags": [ "Catalog" ], "summary": "List active sets ordered by their newest product release.", "operationId": "GetSets", "responses": { "200": { "description": "OK" } } } }, "/api/v1/products": { "get": { "tags": [ "Catalog" ], "summary": "List active dated products, optionally filtered by set code.", "operationId": "GetProducts", "parameters": [ { "name": "setCode", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "ApiKeyRequestStatus": { "type": "integer" }, "ApproveKeyOptions": { "required": [ "tier", "lifetimeDays" ], "type": "object", "properties": { "tier": { "type": [ "null", "string" ] }, "lifetimeDays": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "ArtistWriteRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "socialLink": { "type": [ "null", "string" ] } } }, "CanonicalCardCreateRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "cardType": { "type": [ "null", "string" ] }, "attack": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "defense": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "beastAttributes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "specialAttributes": { "type": [ "null", "string" ] }, "additionalRules": { "type": [ "null", "string" ] } } }, "CanonicalCardUpdateRequest": { "type": "object", "properties": { "cardType": { "type": [ "null", "string" ] }, "attack": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "defense": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "beastAttributes": { "type": [ "null", "array" ], "items": { "type": "string" } }, "specialAttributes": { "type": [ "null", "string" ] }, "additionalRules": { "type": [ "null", "string" ] } } }, "CardDetailDto": { "required": [ "printingId", "cardId", "name", "cardType", "additionalRules", "setId", "setName", "setCode", "specialAttributes", "flavorText", "attack", "defense", "beastAttributes", "imageUrl", "otherPrintings", "productId", "productName", "productType", "productReleaseDate", "cardNumber", "baseCardNumber", "styles", "rarity", "serializedQuantity", "artistId", "artistName", "artistSocialLink" ], "type": "object", "properties": { "printingId": { "type": "string", "format": "uuid" }, "cardId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "cardType": { "type": "string" }, "additionalRules": { "type": [ "null", "string" ] }, "setId": { "type": "string", "format": "uuid" }, "setName": { "type": "string" }, "setCode": { "type": "string" }, "specialAttributes": { "type": [ "null", "string" ] }, "flavorText": { "type": [ "null", "string" ] }, "attack": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "defense": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "beastAttributes": { "type": "array", "items": { "type": "string" } }, "imageUrl": { "type": [ "null", "string" ] }, "otherPrintings": { "type": "array", "items": { "$ref": "#/components/schemas/SiblingPrintingDto" } }, "productId": { "type": [ "null", "string" ], "format": "uuid" }, "productName": { "type": [ "null", "string" ] }, "productType": { "type": [ "null", "string" ] }, "productReleaseDate": { "type": [ "null", "string" ], "format": "date" }, "cardNumber": { "type": [ "null", "string" ] }, "baseCardNumber": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "styles": { "type": "array", "items": { "type": "string" } }, "rarity": { "type": "string" }, "serializedQuantity": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "artistId": { "type": "string", "format": "uuid" }, "artistName": { "type": "string" }, "artistSocialLink": { "type": "string" } } }, "CardSummaryDto": { "required": [ "printingId", "cardId", "name", "cardType", "beastAttributes", "setName", "setCode", "imageUrl", "printingCount", "productId", "productName", "productType", "productReleaseDate", "cardNumber", "baseCardNumber", "styles", "rarity", "serializedQuantity", "artistId", "artistName", "artistSocialLink" ], "type": "object", "properties": { "printingId": { "type": "string", "format": "uuid" }, "cardId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "cardType": { "type": "string" }, "beastAttributes": { "type": "array", "items": { "type": "string" } }, "setName": { "type": "string" }, "setCode": { "type": "string" }, "imageUrl": { "type": [ "null", "string" ] }, "printingCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "productId": { "type": [ "null", "string" ], "format": "uuid" }, "productName": { "type": [ "null", "string" ] }, "productType": { "type": [ "null", "string" ] }, "productReleaseDate": { "type": [ "null", "string" ], "format": "date" }, "cardNumber": { "type": [ "null", "string" ] }, "baseCardNumber": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "styles": { "type": "array", "items": { "type": "string" } }, "rarity": { "type": "string" }, "serializedQuantity": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "artistId": { "type": "string", "format": "uuid" }, "artistName": { "type": "string" }, "artistSocialLink": { "type": "string" }, "attack": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "defense": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "specialAttributes": { "type": [ "null", "string" ] }, "additionalRules": { "type": [ "null", "string" ] } } }, "PagedResultOfCardSummaryDto": { "required": [ "items", "page", "pageSize", "totalCount" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CardSummaryDto" } }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PagedResultOfPrintingUrlIdentityDto": { "required": [ "items", "page", "pageSize", "totalCount" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrintingUrlIdentityDto" } }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PrintingImageFinalizeRequest": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid" } } }, "PrintingImageUploadGrantRequest": { "type": "object", "properties": { "contentType": { "type": [ "null", "string" ] } } }, "PrintingUrlIdentityDto": { "required": [ "printingId", "cardNumber", "name" ], "type": "object", "properties": { "printingId": { "type": "string", "format": "uuid" }, "cardNumber": { "type": "string" }, "name": { "type": "string" } } }, "PrintingWriteRequest": { "type": "object", "properties": { "cardId": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "artistId": { "type": "string", "format": "uuid" }, "cardNumber": { "type": [ "null", "string" ] }, "styles": { "type": [ "null", "array" ], "items": { "type": "string" } }, "rarity": { "type": [ "null", "string" ] }, "serializedQuantity": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "flavorText": { "type": [ "null", "string" ] } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProductWriteRequest": { "type": "object", "properties": { "setId": { "type": "string", "format": "uuid" }, "name": { "type": [ "null", "string" ] }, "productType": { "type": [ "null", "string" ] }, "releaseDate": { "type": [ "null", "string" ], "format": "date" } } }, "SetWriteRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "code": { "type": [ "null", "string" ] } } }, "SiblingPrintingDto": { "required": [ "printingId", "setId", "setName", "setCode", "imageUrl", "productId", "productName", "productType", "productReleaseDate", "cardNumber", "baseCardNumber", "styles", "rarity", "serializedQuantity", "artistId", "artistName", "artistSocialLink" ], "type": "object", "properties": { "printingId": { "type": "string", "format": "uuid" }, "setId": { "type": "string", "format": "uuid" }, "setName": { "type": "string" }, "setCode": { "type": "string" }, "imageUrl": { "type": [ "null", "string" ] }, "productId": { "type": [ "null", "string" ], "format": "uuid" }, "productName": { "type": [ "null", "string" ] }, "productType": { "type": [ "null", "string" ] }, "productReleaseDate": { "type": [ "null", "string" ], "format": "date" }, "cardNumber": { "type": [ "null", "string" ] }, "baseCardNumber": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "styles": { "type": "array", "items": { "type": "string" } }, "rarity": { "type": "string" }, "serializedQuantity": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "artistId": { "type": "string", "format": "uuid" }, "artistName": { "type": "string" }, "artistSocialLink": { "type": "string" } } }, "SubmitAccessRequest": { "required": [ "email", "organizationName", "intendedUse" ], "type": "object", "properties": { "email": { "type": "string" }, "organizationName": { "type": [ "null", "string" ] }, "intendedUse": { "type": "string" } } } } }, "tags": [ { "name": "API Keys" }, { "name": "Catalog" }, { "name": "Catalog (Admin)" }, { "name": "API Keys (Admin)" } ] }