# Search cards

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

GET https://app.holofolder.com/app/api/v1/cards

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

```json
{
  "operationId": "list_cards",
  "summary": "Search cards",
  "description": "Browse all card printings, including Trainers and Energy, with pagination. Records declare game:pokemon; IDs are globally unique opaque application IDs, not provider-local keys.\n\nRequired permissions: `catalog:read`. MCP tool: `list_cards`.",
  "tags": [
    "Catalog"
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 1024
      }
    },
    {
      "name": "language",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "en",
          "fr",
          "de",
          "es",
          "it",
          "pt-br",
          "ja",
          "ko"
        ]
      }
    },
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 80
      }
    },
    {
      "name": "set",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    {
      "name": "series",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    {
      "name": "illustrator",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 200
      }
    },
    {
      "name": "pokemon",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9999
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "data": {
                "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": {
                      "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",
                    "details",
                    "artworkRef",
                    "image",
                    "imageAvailability",
                    "imageLanguage",
                    "attribution"
                  ],
                  "additionalProperties": false
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "data",
              "nextCursor"
            ],
            "additionalProperties": {}
          }
        }
      }
    },
    "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
          }
        }
      }
    }
  }
}
```