# Suggest cards

Source: https://holofolder.com/app/docs/reference/catalog/suggest-cards

POST https://app.holofolder.com/app/api/v1/cards/suggest

OpenAPI operation (parameters, authentication, request body and responses):

```json
{
  "operationId": "suggest_cards",
  "summary": "Suggest cards",
  "description": "Cards that would fit alongside a group of cards, such as the cards on one binder page. Ranked by picture first (cards that look like several of the given cards come first, from image fingerprints; reprints of the same artwork are left out), then filled up with cards sharing a Pokémon, illustrator, energy type or set. pokemon adds Pokédex numbers for pockets kept for a Pokémon without a card. The given cards are never returned; leave out any others you already have yourself. At most 60 cards.\n\nRequired permissions: `catalog:read`. MCP tool: `suggest_cards`.",
  "tags": [
    "Catalog"
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "parameters": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "cardIds": {
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "description": "Card IDs already on the page, e.g. [\"base1-4\", \"base1-2\"]."
            },
            "pokemon": {
              "description": "Pokédex numbers.",
              "maxItems": 40,
              "type": "array",
              "items": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9999
              }
            },
            "language": {
              "type": "string",
              "enum": [
                "en",
                "fr",
                "de",
                "es",
                "it",
                "pt-br",
                "ja",
                "ko"
              ]
            },
            "includeDetails": {
              "description": "Include details (the stored provider record). Default: true on REST, false on MCP.",
              "type": "boolean"
            }
          },
          "required": [
            "cardIds"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "language": {
                "type": "string"
              },
              "cards": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "description": "Globally unique opaque application ID, never a reusable provider-local key."
                    },
                    "game": {
                      "type": "string",
                      "const": "pokemon"
                    },
                    "canonicalId": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "description": "Globally unique opaque application ID, never a reusable provider-local key."
                    },
                    "aliasIds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200,
                        "description": "Globally unique opaque application ID, never a reusable provider-local key."
                      }
                    },
                    "localId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "names": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {}
                    },
                    "language": {
                      "type": "string"
                    },
                    "set": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "description": "Globally unique opaque application ID, never a reusable provider-local key."
                        },
                        "game": {
                          "type": "string",
                          "const": "pokemon"
                        },
                        "name": {
                          "type": "string"
                        },
                        "officialCardCount": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "releaseDate": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "game",
                        "name",
                        "officialCardCount",
                        "releaseDate"
                      ],
                      "additionalProperties": false
                    },
                    "seriesId": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "description": "Globally unique opaque application ID, never a reusable provider-local key."
                    },
                    "category": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "rarity": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "hp": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "illustrator": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "types": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "variants": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "boolean"
                      }
                    },
                    "externalIds": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "description": "Provider-local IDs keyed by source, scoped to this record game. Not application IDs or aliases."
                    },
                    "details": {
                      "description": "Stored provider record, with includeDetails.",
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {}
                    },
                    "artworkRef": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "image": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "imageAvailability": {
                      "type": "string",
                      "enum": [
                        "available",
                        "missing",
                        "unavailable"
                      ]
                    },
                    "imageLanguage": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "attribution": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "game",
                    "canonicalId",
                    "aliasIds",
                    "localId",
                    "name",
                    "names",
                    "language",
                    "set",
                    "seriesId",
                    "category",
                    "rarity",
                    "hp",
                    "illustrator",
                    "types",
                    "variants",
                    "externalIds",
                    "artworkRef",
                    "image",
                    "imageAvailability",
                    "imageLanguage",
                    "attribution"
                  ],
                  "additionalProperties": false
                },
                "description": "Most alike first."
              }
            },
            "required": [
              "language",
              "cards"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "400": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "401": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "402": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "403": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "404": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "409": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "413": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "422": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "429": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "503": {
      "description": "See the API conventions page.",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "error"
            ],
            "additionalProperties": false
          }
        }
      }
    }
  }
}
```