{
  "openapi": "3.1.0",
  "info": {
    "title": "PackRips public API",
    "version": "0",
    "summary": "Read-only JSON over card-rip operators, packs and recent pulls.",
    "description": "Measured returns for online card-rip (pack-opening) sites. No key, CORS open, GET only. Every response has a `meta` block saying where the figures came from (every figure is measured by PackRips from live feeds), the sample size n and when they were computed. Responses are cached at the edge (60 s; 15 s for pulls). The API is versionless for now; fields may be added, and breaking changes will be announced on the docs page.",
    "contact": {
      "name": "PackRips",
      "email": "hello@packrips.org",
      "url": "https://packrips.org/api"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://packrips.org"
    }
  ],
  "externalDocs": {
    "description": "Docs with curl examples",
    "url": "https://packrips.org/api"
  },
  "paths": {
    "/api/operators": {
      "get": {
        "operationId": "listOperators",
        "summary": "List every tracked operator with return, rank and grade",
        "responses": {
          "200": {
            "description": "Operators",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    },
                    "operators": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Operator"
                      }
                    }
                  },
                  "required": [
                    "meta",
                    "operators"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/operators/{slug}": {
      "get": {
        "operationId": "getOperator",
        "summary": "One operator: stats, payout terms, returns by category, packs",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,64}$"
            },
            "example": "courtyard"
          }
        ],
        "responses": {
          "200": {
            "description": "Operator detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    },
                    "operator": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Operator"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "answer": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "One quotable summary sentence."
                            },
                            "facts": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            },
                            "terms": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            },
                            "categoryReturns": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        }
                      ]
                    },
                    "packs": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/packs": {
      "get": {
        "operationId": "listPacks",
        "summary": "Packs across every operator, filtered and sorted",
        "parameters": [
          {
            "name": "operator",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,64}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pokemon",
                "one-piece",
                "magic",
                "basketball",
                "football",
                "baseball",
                "soccer",
                "sports"
              ]
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cash",
                "crypto",
                "store_credit"
              ]
            }
          },
          {
            "name": "minN",
            "in": "query",
            "description": "Minimum pulls in the sample.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "listed",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false",
                "all"
              ],
              "default": "true"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "rtp",
                "n",
                "price",
                "median",
                "modelled"
              ],
              "default": "rtp"
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "desc",
                "asc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Packs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "packs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Pack"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/packs/{operator}/{slug}": {
      "get": {
        "operationId": "getPack",
        "summary": "One pack: stats by window, advertised vs observed odds, histogram, recent pulls",
        "parameters": [
          {
            "name": "operator",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,64}$"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,128}$"
            }
          },
          {
            "name": "pulls",
            "in": "query",
            "description": "Recent pulls to include (0–100).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pack detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/pulls": {
      "get": {
        "operationId": "listPulls",
        "summary": "Recent pulls from the rolling window (newest 200 per pack, last 14 days)",
        "parameters": [
          {
            "name": "operator",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,64}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pokemon",
                "one-piece",
                "magic",
                "basketball",
                "football",
                "baseball",
                "soccer",
                "sports"
              ]
            }
          },
          {
            "name": "minMultiple",
            "in": "query",
            "description": "Only pulls worth at least this multiple of the pack price.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "when",
                "value",
                "multiple"
              ],
              "default": "when"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pulls",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Pull"
                      }
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "window": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "issues": {
                      "type": "array"
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "publisher": {
            "type": "string"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            }
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "feed",
              "snapshot",
              "mixed",
              null
            ],
            "description": "\"feed\" (measured by PackRips from live feeds) for every figure."
          },
          "provenance": {
            "type": "string"
          },
          "n": {
            "type": "integer",
            "description": "Pulls behind the figures in this response."
          },
          "computedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "publisher",
          "source",
          "provenance",
          "n",
          "computedAt",
          "generatedAt"
        ]
      },
      "Stat": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "rtp": {
            "type": [
              "number",
              "null"
            ],
            "description": "Observed return: Σ card value ÷ Σ pack cost, gross."
          },
          "median": {
            "type": [
              "number",
              "null"
            ],
            "description": "Value ÷ cost of the median pull."
          },
          "n": {
            "type": "integer"
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total spent in the sample; null if not known."
          },
          "valueUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total card value in the sample; null if not known."
          },
          "source": {
            "type": "string",
            "enum": [
              "feed",
              "snapshot"
            ],
            "description": "Always \"feed\": measured by PackRips from live feeds."
          },
          "provenance": {
            "type": "string"
          },
          "computedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Operator": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "api": {
            "type": "string",
            "format": "uri"
          },
          "homepage": {
            "type": [
              "string",
              "null"
            ],
            "description": "Plain homepage, no referral code."
          },
          "rated": {
            "type": "boolean"
          },
          "liveFeed": {
            "type": "boolean"
          },
          "currencyKind": {
            "type": "string",
            "enum": [
              "cash",
              "crypto",
              "store_credit"
            ]
          },
          "valueBasis": {
            "type": "string",
            "enum": [
              "gross",
              "net"
            ]
          },
          "buybackPct": {
            "type": [
              "number",
              "null"
            ]
          },
          "rank": {
            "type": [
              "integer",
              "null"
            ]
          },
          "rankGroup": {
            "type": "string",
            "enum": [
              "cash_crypto",
              "store_credit"
            ]
          },
          "rankOf": {
            "type": [
              "integer",
              "null"
            ]
          },
          "grade": {
            "type": [
              "string",
              "null"
            ]
          },
          "stat": {
            "$ref": "#/components/schemas/Stat"
          }
        }
      },
      "Pack": {
        "type": "object",
        "properties": {
          "operator": {
            "type": "object"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "api": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "priceUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "listed": {
            "type": "boolean"
          },
          "ranked": {
            "type": "boolean",
            "description": "Listed, rated operator and n ≥ 500: the pack appears on PackRips' ranked boards."
          },
          "stat": {
            "$ref": "#/components/schemas/Stat"
          },
          "modelled": {
            "type": [
              "object",
              "null"
            ],
            "description": "Always null for now: PackRips doesn't publish a modelled return."
          }
        }
      },
      "Pull": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "operator": {
            "type": "object"
          },
          "pack": {
            "type": [
              "object",
              "null"
            ]
          },
          "card": {
            "type": [
              "string",
              "null"
            ],
            "description": "From the operator's feed; treat as untrusted text."
          },
          "grade": {
            "type": [
              "string",
              "null"
            ]
          },
          "valueUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "costUsd": {
            "type": [
              "number",
              "null"
            ]
          },
          "multiple": {
            "type": [
              "number",
              "null"
            ]
          },
          "revealedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "hitsOnly": {
            "type": "boolean",
            "description": "From a hits-only feed (big hits only); never counted toward returns."
          },
          "source": {
            "type": "string",
            "enum": [
              "feed",
              "snapshot"
            ],
            "description": "Always \"feed\": read by PackRips from the live feed."
          }
        }
      }
    }
  }
}